The REPP API is a Level 3 REST API that uses JSON for data serialization but can also be explored as HTML in a browser.
Authentication
All requests to the REPP API must be over HTTPS and authenticated with either an API Key and Secret via HTTP Basic Authentication or with an access token provided after a user gives authorization using OAuth 2.
For more information on using REPP’s OAuth 2 implementation read the OAuth Guide.
To obtain an API Key, please complete the Request an API Key form.
Structure
If used properly, the structure of the API will help you and your application avoid making calls to resources that either you don’t have access to or that the current state of the resource doesn’t allow. This is called HATEOAS (Hypermedia as the Engine of Application State) and is the corner stone to the flexibility of our API.
Services
The API is logically separated by typical use into high level services. For example the People Service contains resources for retrieving and manipulating information on people. Each service has a root URI that is the starting point for all resources within that service. The service URIs are the only documented endpoints. All other resource endpoints are discoverable within related resources and should never be hard coded into an application without a complete understanding of the negative side effects of doing so. A complete list of resource endpoints is available within a service can be accessed by performing a GET request on the service’s root URI.
For example:
curl -u API_KEY:API_SECRET -H "Accept: application/json" https://api.myrepp.com/people
would return something like the following, depending on permissions:
{
"_type": "home",
"name": "people",
"title": "People API",
"description": "API for accessing basic people information",
"version": "1",
"rootPath": "/people",
"basePath": "/",
"_links": {
"all": {
"href": "https://api.myrepp.com/people/all"
},
"idVerification": {
"template": "https://api.myrepp.com/people{/username}/idVerification"
},
"person": {
"template": "https://api.myrepp.com/people{/username}{?embed,fields}"
},
"home": {
"href": "https://api.myrepp.com/people"
},
"self": {
"href": "https://api.myrepp.com/people"
}
},
"_actions": {
"get": {
"href": "https://api.myrepp.com/people",
"method": "GET"
}
}
}
Resources
Each endpoint represents a specific resource which contains the resource’s properties, actions that can be performed on the resource, as well as links to related resources. In the service example above, the response contains an object that represents the People Service. Properties _type
, _links
, _embedded
, and _actions
are available on all resources.
Property |
Description |
_type |
A String that represents the type of resource that was returned with the response. |
_links |
An Object containing links to related resources. |
_links.[rel] |
Describes the rel or relationship of the link to the current resource. |
_links.[rel].href |
URI to access the related resource. Optional, either a href or template will be available. |
_links.[rel].template |
URI Template that can be used to build the href to the related resource. Optional, either a href or template will be available. |
_links.[rel].title |
Provides additional information about the related resource. Optional. |
_actions.[name] |
An Object describing actions that can be taken on the current resource, similar to HTML forms. |
_actions.[name].href |
URI used to complete the action, similar to a form’s action. |
_actions.[name].method |
HTTP method used to complete the action, similar to a form’s method. |
_actions.[name].params |
Object describing parameters that can be passed to the action’s endpoint. |
_actions.[name].params.[param] |
Name of the parameter. |
_actions.[name].params.[param].type |
Type of the parameter. Possible values are string, number, date, datetime, color, email, or url. |
_actions.[name].params.[param].location |
Location of the parameter on the request. Possible values are query, body, or path. |
_actions.[name].params.[param].options |
An array of possible values of the parameter. An error will be returned if the param doesn’t match a given option. |
_actions.[name].params.[param].pattern |
A regular expression that the parameter value must match. |
_actions.[name].params.[param].min |
The minimum possible value of the parameter. Numbers and dates are both supported. |
_actions.[name].params.[param].max |
The maximum possible value of the parameter. Numbers and dates are both supported. |
_embedded.[rel] |
Resources may allow linked resources to be embedded in a single response. Embedded resources will be available under _embedded with the same key as it’s _links reference. |
The links and actions returned on a resource are limited by the permissions granted to the calling API client. Therefore, the documentation may include information that you do not have access to.
The links home
and self
are present in all resources and represent a link back to the service root and the link to the current resource respectively.
Usage
Requests
Requests are made using standard HTTP requests. As mentioned above, resource endpoints are documented but should be obtained by making a GET request to the service URI instead. This is done to provide maximum flexibility and discoverability of the API.
See the documentation on a specific resource for the action parameter information for a request. Each parameter has a location
that identifies where on the request it should be located. The options are path
, query
, and body
. Path parameters are used to build out the URI for the resource. Query parameters can be added to the requests query string. Body parameters must be included in the requests body either as application/x-www-form-urlencoded
or as application/json
.
IMPORTANT: Make sure the Accept
header of your requests is set to application/json
otherwise HTML will be returned instead of JSON.
Responses
If the Accept
header of a request is set to application/json
the response will be a JSON encoded object. If no accept header is specified HTML will be returned.
See the documentation on a specific resource to see what properties, links and actions are available.
Libraries
A node/javascript client implementation will be available shortly for use. If you are interested in an implementation in a different language please contact support@myrepp.com.
Error Handling
The API uses HTTP status codes to report errors. If all is well you will see a response code in the 200s
. If an error occurred while processing the request, a response code in the 500s
usually means something went wrong on our side whereas a response code in the 400s
means something needs to be corrected on your side. Either way the body of the response will contain an object describing what went wrong.
Error objects have the following properties:
Property |
Description |
name |
A string with the camel-case formatted name of the error that occurred. |
message |
A string describing the error and may provide information on resolution. |
status |
The HTTP status code that was returned on the request. |
errors |
An array of “sub-errors” that caused the request to fail, if any. Most commonly validation errors. |
If an error in the 500s
is encountered, please send a detailed report of the request and any additional information needed to reproduce the error to support@myrepp.com or use the REPP API Issue Tracker.
Rate Limiting
All API requests are rate limited to 500 requests per hour based on originating IP address. Each response contains the current hourly limit in the response header X-RateLimit-Limit
and the number of calls still available before reaching the limit in X-RateLimit-Remaining
. Once the limit has been exceeded, further responses will fail until the time frame has expired.
If your application needs to make more than 500 requests per hour, please contact support@myrepp.com to discuss options.