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.