RAMS ID Endpoints - HearstCorp/rover-wiki GitHub Wiki
RAMS ID
Based on the RAMSID Client API.
API Documentation
The API accepts POST requests to
https://dev-rover.dev.mediaos.hearst.io/api/v1/
https://stage-rover.mediaos.hearst.io/api/v1/
https://prod-rover.mediaos.hearst.io/api/v1/
and always responds in JSON.
All API requests require an auth token, which can be obtained by querying the client endpoint.
Client
To obtain an auth token send a POST request to:
/api/v1/client/[id]
Replacing [id]
with your client ID.
The parameters in the POST body should be:
- timestamp - the current unix timestamp
- signature - base64 encoded hash value of the timestamp using HMAC-SHA256 with your client secret key
Auth tokens expire after 4 hours so you will need to refresh them appropriately
Example response:
{"data":{"token":"0GknoDgaFOx1xI8pEWUdbM0gK4UzWmjb"}}
Users
User data
To query a specific user send a POST request to:
/api/v1/user/[id]
Replacing [id]
with either a numeric user ID or username.
The parameters in the POST body should be:
- site (optional)
- token
If you pass site
as a parameter the API will include the user's role for that site.
Example response:
{"data":{"id":1,"first_name":"Dev","last_name":"Account","username":"dev","email":"[email protected]","created_at":"2014-04-16 13:22:26","updated_at":"2014-04-24 10:34:21","role":"administrator","biography":"","display_name":"","facebook_username":"","google_author_id":"","instagram_username":"","job_title":"","meta_description":"","meta_keywords":"","meta_title":"","middle_name":"","photo":"","pinterest_username":"","public_email":"","subheading":"","suffix":"","title":"","twitter_username":""}}
Multiple user's data
You can send requests for multiple user's data to the above endpoint by seperating the user ID's or usernames with a comma.
Example:
/api/v1/user/1,2,5,8,9
There is a limit of 100 ID's or usernames allowed in the URL. User's that do not exist will be skipped in the output.
Multiple users' data paginated
A new endpoint has been added to retrieve all users for a given site as a paginated result set.
The api has been configured to return 100 results per page. To change the result per page
modify the APIUserController::$rpp
property.
example to request users across all sites:
/api/v1/users
example to request users by site tag:
/api/v1/users/cosmo
example to request a specific page from the result set:
/api/v1/users/page/2
or
/api/v1/users/cosmo/page/2
Example Response:
{
"data":[
{
"id":1,
"first_name":"Dev",
"last_name":"Account",
"username":"dev",
"email":"[email protected]",
"created_at":"2015-03-24 13:38:54",
"updated_at":"2015-03-24 13:38:54"
}
],
"pagination":{
"total":3,
"count":1,
"per_page":1,
"current_page":1,
"total_pages":3,
"links":{"next":"http://localhost/api/v1/users/cosmo/page/2"}
}
}
Login verification
To validate a user's login credentials send a POST request to:
/api/v1/login
The parameters in the POST body should be:
- username (email address)
- password
- site
- token
If the credentials are valid the API will respond with the user's data as above. If invalid it will respond with an error.
Search
To search for a user send a POST request to:
/api/v1/search
The parameters in the POST body should be:
- any combination of: first_name, last_name or email
- token
You can use %
to indicate a wildcard in the search string.
The API will respond with a paginated list of user data as above.
Errors
If an error occurs the API will return a 400 Bad Request
HTTP status code, along with an error message and error code in the JSON response.
Example response:
{"error":{"message":"Invalid auth token","code":3}}
Error codes
Code | Message |
---|---|
1 | Invalid client ID |
2 | Invalid timestamp |
3 | Invalid signature |
4 | Invalid auth token |
5 | Site not found |
6 | Role not found |
7 | Validation errors |
8 | User not found |
9 | User password incorrect |
10 | User cannot access this site |
11 | User could not be saved |
12 | Maximum number of users requested has been reached |
When a validation error occurs an additional info
field will contain the validation message.