Back to top

Seagrass Spotter API

Welcome

Please note, this API is still in development, and may change at any time.

This API is used for the Seagrass Spotter website, and the accompanying mobile app. As Seagrass Spotter is a non-profit research project, all the data is open and in the public domain. If you use the API for any project, we’d love to hear from you!

Usage

To get data from the API, simply send a GET request to the relevant endpoint. For example, if you want to get all the sightings, you can GET /sightings.

Some methods require authentication. The API uses JSON Web Tokens for authentication. To obtain a token, make a request to /auth/login with your credentials, and attach the token in the headers for thoses requests.



Authentication

Methods used to authenticate a user. Use this resource to deal with the registration, login and password functionality for an API user. To modify the user’s data, look at the /user endpoints.

Login

Login
POST/login

Logs in a user with an email and password, and returns a user token. The email can be either the user’s email or username.

Example URI

POST /login
URI Parameters
HideShow
email
string (required) 

User email or username

password
string (required) 

User password

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "username": "foo",
  "password": "bar"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "access_token": "a1b2c3",
  "token_type": "bearer",
  "expires_in": 3600
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "You need to provide the username or email, and the password",
  "status_code": 400
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Your details are not recognised",
  "status_code": 401
}

Register

Register
POST/register

Register a user for the site, and return a user token.

Example URI

POST /register
URI Parameters
HideShow
email
string (required) 

User email

password
string (required) 

User password

name
string (required) 

User’s real name

username
string (required) 

Username handle

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "username": "foo",
  "password": "bar",
  "name": "Foo Bar",
  "email": "foo@bar.com"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "access_token": "a1b2c3",
  "token_type": "bearer",
  "expires_in": 3600
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": {
    "email": [
      "The email has already been taken."
    ],
    "username": [
      "The username has already been taken."
    ]
  },
  "status_code": 400
}

Update Password

Update Password
POST/update-password

Updates the user’s password

Example URI

POST /update-password
URI Parameters
HideShow
old_password
string (required) 

User’s old password

new_password
string (required) 

User’s new password

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "old_password": "foo",
  "new_password": "bar"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "access_token": "a1b2c3",
  "token_type": "bearer",
  "expires_in": 3600
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "old_password": "Your old password is incorrect."
}

Forgot Password

Forgot Password
POST/forgot-password

Requests a reset token for a user, and emails them instructions of how to reset

Example URI

POST /forgot-password
URI Parameters
HideShow
email
string (required) 

The email of the user to reset

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "email": "foo@foo.com"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  "An email with details on how to reset your password has been sent"
]
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Your email is not recognised"
}

Reset Password

Reset Password
POST/reset-password

Resets a user’s password after they have requested a reset, and returns the JWT

Example URI

POST /reset-password
URI Parameters
HideShow
email
string (required) 

The email of the user to reset

reset_token
string (required) 

The reset token from the email

password
string (required) 

The new password

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "0": {
    "reset_token": "ajjsgydbcvlqpe876v8bn3wu"
  },
  "1": {
    "password": "p455w0rd"
  },
  "email": "foo@foo.com"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "access_token": "a1b2c3",
  "token_type": "bearer",
  "expires_in": 3600
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
[
  "There's no reset requested for this user."
]

Logout

Logout
POST/logout

Invalidates the user’s token

Example URI

POST /logout
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Successfully logged out"
}

Users

User methods.

Get Users

Get Users
GET/user

Gets all the users. You must be an admin to get all the users

Example URI

GET /user
Response  200
HideShow
Headers
Content-Type: application/json
Body
[]

Get User

Get User
GET/user/:id

Gets a single user

Example URI

GET /user/:id
Response  200
HideShow
Headers
Content-Type: application/json
Body
[]

Delete

Delete
POST/update-user/:id

Deletes an existing user and all of their sightings

Example URI

POST /update-user/:id

Update

Update
POST/update-user/:id

Updates an existing user’s data

Example URI

POST /update-user/:id

Sightings

Sighting methods.

Get Sightings

Get Sightings
GET/sighting

Gets all the sightings

Example URI

GET /sighting
Response  200
HideShow
Headers
Content-Type: application/json
Body
[]

Get Sighting

Get Sighting
GET/sighting/:id

Gets a single sighting

Example URI

GET /sighting/:id
Response  200
HideShow
Headers
Content-Type: application/json
Body
[]

Create

Create
POST/sighting

Creates a sighting

Example URI

POST /sighting
URI Parameters
HideShow
email
string (required) 

User email or username

password
string (required) 

User password

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "username": "foo",
  "password": "bar"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "access_token": "a1b2c3",
  "token_type": "bearer",
  "expires_in": 3600
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "You need to provide the username or email, and the password",
  "status_code": 400
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Your details are not recognised",
  "status_code": 401
}

Update

Update
POST/sighting

Updates an existing sighting

Example URI

POST /sighting

Delete

Delete
POST/delete-sighting

Delete’s a sighting and any media along with it

Example URI

POST /delete-sighting

Generated by aglio on 02 Feb 2018