+ The Foundations API is organised around + + + REST + + + with all resources accessible using standard + + HTTP methods + + and returning predictable + + response codes + + . All request and response bodies, including errors, are encoded in + + JSON + + and served over + + + HTTPS TLS v1.1+ + + to ensure data privacy and security. +
++ Our API resources are secured and require an + + + authorization JWT bearer token + + to be submitted as part of requests sent to protected endpoints. For more information how our APIs are secured, please see + + + Authorization + + . +
++ Alternatively, our + + Developer Sandbox + + provides a quick start experience to quickly get to grips with the platform and start developing. +
++ Foundation APIs present a uniform interface for performing CRUD (create, retrieve, update, delete) operations. Each endpoint adheres to REST guidelines to map the correct verb to the operation being performed. Our APIs support the following HTTP methods: +
++ Foundation APIs use standardised HTTP status codes to indicate whether a request has been successful or has resulted in an error. Below is a listing of the codes our APIs may return and their meaning: +
++ The access token must then be sent in the Authorization header to be able to access protected Foundation APIs. +
+
+
+ Authorization : Bearer <access token>
+
+
+ Upon recieving an access token, the Foundation will validate the token to ensure: +
++ You can use the Foundation API in Sandbox mode which provides a set of demonstration data that can be interacted with without affecting any client environment. +
++ Upon registering with our developer portal, you can immediately get familiar with the functionality our APIs offer and enjoy a hurdle free route to start developing your application +
++ Sandbox mode supports processing of all read and write requests so that you can build and test in confidence before submitting your application to our Marketplace. +
++ To access the sandbox, you'll need to register for a developer account at our Portal. You're then able to simply use those credentials provide them to our Authorization services in the normal way. The access token generated for your developer credentials will point our APIs at your sandbox data. +
++ Alternatively, our Interactive API Explorer will automatically grant access to sandbox data when you're logged into the Developer Portal. +
++ Unsuccessful requests return an error response in JSON format. This includes a status code, a time stamp and textual description of the error: +
++
+
+ Content-Type: application/json
+
+{
+ "statusCode": 404,
+ "dateTime": "2019-04-23T18:25:43.511Z",
+ "description": "Contact RPT19000001 was not found."
+}
+
+
+
+
+ + Validation errors will also include a breakdown of the problems with the submitted payload: +
++
+
+ Content-Type: application/json
+
+{
+ "statusCode": 422,
+ "dateTime": "2019-04-23T18:25:43.511Z",
+ "description": "The submitted payload has failed validation.
+ See the errors list for more information.",
+ "errors": [
+ {
+ "field" : "caption",
+ "message" : "Must be less than 50 characters in length."
+ }
+ ]
+}
+
+
+
+
+ + You can make 1000 requests per minute to our APIs. Each response will include HTTP headers to provide information on the current rate limit statistics. +
+
+
+ If the rate limit is hit, a response similar to below will be issued:
+
+
+
+ HTTP/1.1 429 Too Many Requests X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1402010983 Retry-After: 30
+
+ Content-Type: application/json
+
+{
+ "statusCode": 429,
+ "dateTime": "2019-04-23T18:25:43.511Z",
+ "description": "Rate limit for API requests has been hit.
+ Your limit is 1000 requests per minute.
+ This limit will be reset in 30 seconds."
+}
+
+
+
+
+ + All collection API resources can be paged and share a common structure in their responses. Page size and offset is controlled by use of standardised query strings. +
++ Unless documented, the default page size is 25 and the maximum is 50. +
+
+
+
+
+ http://foundations.reapit.com/contacts?pageSize=10&pageNumber=2
+
+
+
+
+ Content-Type: application/json
+
+{
+ "pageNumber": 2,
+ "pageSize": 10,
+ "pageCount": 10,
+ "totalCount" : 142,
+ "data" : [
+ ...
+ ]
+}
+
+
+
+
+ + Some of the top level resources made available by the platform include resource expansion functionality. When fetching data from a resource expansion enabled endpoint, clients can optionally request that a response includes data from one or more related resources. +
++ This ability is to designed to reduce the number of required client-server roundtrips to obtain the data that a client needs for a specific use-case. +
++ Query parameters are used to govern this functionality, please see the specific documention of each end point for details. +
++ The example request below will fetch a list of contacts with resource expansion enabled for the identity checks nested collection: +
+
+
+ http://foundations.reapit.com/contacts?embed=identityChecks
+
+
+ A paged response from the
+
+ /contacts
+
+ request example above:
+
+
+
+ Content-Type: application/json
+
+{
+ "data" :
+ [
+ {
+ "id" : "RPT1900001",
+ "title" : "Mr",
+ "forename" : "David",
+ "surname" : "Smith",
+ ...
+ "embedded": {
+ "identityChecks" :
+ [
+ {
+ "id" : "RPT1900050",
+ "contactId" : "RPT1900001",
+ "status" : "pending",
+ ...
+ }
+ ]
+ }
+ }
+ ],
+ "pageNumber": 1,
+ "pageSize": 25,
+ "pageCount": 25,
+ "totalCount" : 142,
+}
+
+
+
+
+
+ Resources that support editing have a
+
+ metadata
+
+ attribute available in their payload. This attribute can be used to set a JSON data fragment against a specific resource by including the metadata attribute in POST and PATCH requests. This will subsequently be included in future fetches of that resource.
+
+ Metadata should be used to store additional, structured information against an object. This allows our clients to build upon the resource returned by the API and create a point of integration between our platform and third party applications. A common use case would be to store a unique identifier from an external system. +
++ Once metadata has been submitted to a representation, a JSON schema is built and used to validate future metadata submissions to the same endpoint to keep ensure that data is valid and consistant. +
++ Information stored in metadata is specific to your application and is not available to other Reapit or third party applications. Do not store any sensitive information (personally identifiable information, bank details, etc.) as metadata. +
+ + + +`; + +exports[`ApiDocs should match snapshot after changing hash 1`] = ` +Alternatively, our - Developer Sandbox - + provides a quick start experience to quickly get to grips with the platform and start developing.
- Your application must be registered with our Marketplace before it can interact with data, functionality and assets provided by the Foundations API. For more information on how to register your application, see our - - - Marketplace - - documentation. + Your application must be registered with our Marketplace before it can interact with data, functionality and assets provided by the Foundations API. For more information on how to register your application, see our Marketplace documentation.
As part of creating your application, you'll be required to choose the @@ -260,13 +908,7 @@ exports[`ApiDocs should match a snapshot 1`] = ` As part of the installation process, clients are required to agree to the scopes that your application requires before your application becomes accessible to end users. Applications cannot interact with client data or assets without prior approval from the client.
- Once installed, an application can access Foundation services on an end users behalf. The recommended way to achieve this is to use one of our - - Client Libraries - - , however you can interact directly with our APIs as detailed below. + Once installed, an application can access Foundation services on an end users behalf. The recommended way to achieve this is to use one of our Client Libraries, however you can interact directly with our APIs as detailed below.
The Foundations API is organised around{' '} REST {' '} - with all resources accessible using standard HTTP methods and returning - predictable response codes. All request and response bodies, including errors, - are encoded in JSON and served over{' '} + with all resources accessible using standard HTTP methods and returning + predictable response codes. All request and response bodies, including + errors, are encoded in JSON and served over{' '} HTTPS TLS v1.1+ to ensure data privacy and security.
@@ -24,11 +38,11 @@ const ApiDocsPage: React.SFC = () => { Our API resources are secured and require an{' '} authorization JWT bearer token to be submitted as part of requests sent to protected endpoints. For more information how our APIs are secured, please see{' '} - Authorization. + Authorization.- Alternatively, our Developer Sandbox provides a quick start experience to - quickly get to grips with the platform and start developing. + Alternatively, our Developer Sandbox provides a quick start experience + to quickly get to grips with the platform and start developing.
Your application must be registered with our Marketplace before it can interact with data, functionality and - assets provided by the Foundations API. For more information on how to register your application, see our{' '} - Marketplace documentation. + assets provided by the Foundations API. For more information on how to register your application, see our + Marketplace documentation.
As part of creating your application, you'll be required to choose the{' '} @@ -186,8 +200,8 @@ const ApiDocsPage: React.SFC = () => {
Once installed, an application can access Foundation services on an end users behalf. The recommended way to - achieve this is to use one of our Client Libraries, however you can interact - directly with our APIs as detailed below. + achieve this is to use one of our Client Libraries, however you can interact directly with our APIs as + detailed below.
@@ -438,7 +452,7 @@ const ApiDocsPage: React.SFC = () => { "data" : [ ... ] -} +} `} @@ -484,7 +498,7 @@ const ApiDocsPage: React.SFC = () => { "surname" : "Smith", ... "embedded": { - "identityChecks" : + "identityChecks" : [ { "id" : "RPT1900050",