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 ¶
LoginPOST/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
string
(required)User email or username
- password
string
(required)User password
Headers
Content-Type: application/json
Body
{
"username": "foo",
"password": "bar"
}
200
Headers
Content-Type: application/json
Body
{
"access_token": "a1b2c3",
"token_type": "bearer",
"expires_in": 3600
}
400
Headers
Content-Type: application/json
Body
{
"message": "You need to provide the username or email, and the password",
"status_code": 400
}
401
Headers
Content-Type: application/json
Body
{
"message": "Your details are not recognised",
"status_code": 401
}
Register ¶
RegisterPOST/register
Register a user for the site, and return a user token.
Example URI
string
(required)User email
- password
string
(required)User password
- name
string
(required)User’s real name
- username
string
(required)Username handle
Headers
Content-Type: application/json
Body
{
"username": "foo",
"password": "bar",
"name": "Foo Bar",
"email": "foo@bar.com"
}
200
Headers
Content-Type: application/json
Body
{
"access_token": "a1b2c3",
"token_type": "bearer",
"expires_in": 3600
}
400
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 PasswordPOST/update-password
Updates the user’s password
Example URI
- old_password
string
(required)User’s old password
- new_password
string
(required)User’s new password
Headers
Content-Type: application/json
Body
{
"old_password": "foo",
"new_password": "bar"
}
200
Headers
Content-Type: application/json
Body
{
"access_token": "a1b2c3",
"token_type": "bearer",
"expires_in": 3600
}
400
Headers
Content-Type: application/json
Body
{
"old_password": "Your old password is incorrect."
}
Forgot Password ¶
Forgot PasswordPOST/forgot-password
Requests a reset token for a user, and emails them instructions of how to reset
Example URI
string
(required)The email of the user to reset
Headers
Content-Type: application/json
Body
{
"email": "foo@foo.com"
}
200
Headers
Content-Type: application/json
Body
[
"An email with details on how to reset your password has been sent"
]
400
Headers
Content-Type: application/json
Body
{
"message": "Your email is not recognised"
}
Reset Password ¶
Reset PasswordPOST/reset-password
Resets a user’s password after they have requested a reset, and returns the JWT
Example URI
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
Headers
Content-Type: application/json
Body
{
"0": {
"reset_token": "ajjsgydbcvlqpe876v8bn3wu"
},
"1": {
"password": "p455w0rd"
},
"email": "foo@foo.com"
}
200
Headers
Content-Type: application/json
Body
{
"access_token": "a1b2c3",
"token_type": "bearer",
"expires_in": 3600
}
400
Headers
Content-Type: application/json
Body
[
"There's no reset requested for this user."
]
Users ¶
User methods.
Get Users ¶
Get UsersGET/user
Gets all the users. You must be an admin to get all the users
Example URI
200
Headers
Content-Type: application/json
Body
[]
Get User ¶
Get UserGET/user/:id
Gets a single user
Example URI
200
Headers
Content-Type: application/json
Body
[]
Sightings ¶
Sighting methods.
Get Sightings ¶
Get SightingsGET/sighting
Gets all the sightings
Example URI
200
Headers
Content-Type: application/json
Body
[]
Get Sighting ¶
Get SightingGET/sighting/:id
Gets a single sighting
Example URI
200
Headers
Content-Type: application/json
Body
[]
Create ¶
CreatePOST/sighting
Creates a sighting
Example URI
string
(required)User email or username
- password
string
(required)User password
Headers
Content-Type: application/json
Body
{
"username": "foo",
"password": "bar"
}
200
Headers
Content-Type: application/json
Body
{
"access_token": "a1b2c3",
"token_type": "bearer",
"expires_in": 3600
}
400
Headers
Content-Type: application/json
Body
{
"message": "You need to provide the username or email, and the password",
"status_code": 400
}
401
Headers
Content-Type: application/json
Body
{
"message": "Your details are not recognised",
"status_code": 401
}