REPP API Documentation

Overview

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.

REPP API Documentation	Search this site