Overview

ReadiNow allows third party systems to connect to ReadiNow to Create, Update or Delete records of any object within ReadiNow. This is achieved through configurable API endpoints where the Administrator specifies which object to expose to an API.

Definitions:

• API: An application programming interface.Within ReadiNow this is a collection of endpoints that are grouped and secured together in order for third party systems to perform actions on records within ReadiNow
• API Endpoint: An endpoint is a web address that the remote system can use to connect to our system. Each endpoint does either a create, update or delete of a particular record of a nominated object. These Endpoints can be created and configured by the ReadiNow Administrator
• API Key: The authentication mechanism for calling endpoints in an API.

Process:

• Decide which object needs to be exposed to an API
• Create an API (see below)
• Configure the Endpoint which specifies the object and allowed actions (create, update, delete via API)
• Create API key (see below)
• Use the details generated to configure the third party system (or integration tool) to POST, PUT or DELETE (which corresponds to create, update and delete) action to ReadiNow

Creating an API

To create an API:

1. Select Application Menu. The menu appears with available applications.
2. Select Administration. The application displays at the landing page.
3. In the Left Navigation Area, select Integration. The Integration expands to display list.
4. Select APIs. The existing APIs display.
5. Select +NEW. The API form displays.
6. Type the Name in the Name field 
7. Type the Address in the Address field, e.g. the name of application in one word. Please refer to step 4 of creating endpoint.
8. Select the checkbox for Enabled.
9. Select Save to save the details.

Creating an Endpoint for any object

To create an Endpoint for any object:

1. On the Endpoints tab of the newly created API, select +NEW. The menu appears.
2. Select API Resource Endpoint. The API Resource Endpoint form displays.
3. In the Object field, select the Pencil  icon and select from the list e.g. Student.
4. Type the Address in the Address field, e.g. the name of the object in one word. (https://yourseveraddress/spapi/api/yourtenant/yourapiaddress/yourendpoint)
5. Select the checkbox for Enabled.
6. Select fields as required.
7. Select Save to save the details.

Creating an API Key

To create an API Key:

1. Select Application Menu. The menu appears with available applications.
2. Select Administration. The application displays at the landing page.
3. In the Left Navigation Area, select Integration. The Integration  expands to display list.
4. Select API Keys. The existing API Keys display.
5. Select +NEW. The API Key form displays.
6. In the API Key field, enter a guid. E.g. b9c91534-7cc1-4e09-b22f-2808072e333e, or generate one at https://www.guidgenerator.com/.
7. Select the checkbox for Enabled, if not ticked.
8. For Run as user, select a user account such as Administrator (The user account must have access control permission to do whatever you expect the API to do).
9. Under APIs Granted tab, link to the New API (or other API as required).
10. Select Save to save the details.

Using a tool that can simulate making web requests

To get a tool that can simulate making web requests:

1. Use a tool that can simulate making web requests e.g. the Postman Plugin for Chrome.
2. Alternatively, see getpostman.com , or just navigate in the Chrome app store.

Running a request to create a new data record

To run a request to create a new account:

1. Use Postman to issue a request like this: (see image below).
2. Use the 'POST' verb.
3. Use key that is generated (e.g. https://yourseveraddress/spapi/api/yourtenant/yourapiaddress/yourendpoint?key=b9c91534-7cc1-4e09-b22f-2808072e333e).
4. Select the Body tab.
5. Select 'Raw'. The textbox appears.
6. Enter this (case sensitive) query:

   { "field1 of string type":"value of field1",  "field2 of decimal type":234.0 }

7. Set the type to JSON (application/json).
8. Select Send.

Response Codes

When an API call is made, the server will response with a HTTP response code as follows:

HTTP Response Codes

Error Codes

In addition to the standard HTTP response codes, the body of the responsee message may contain an error code. Note that error codes do not form part of the HTTP standard.

Errors in the range E0xxx represent platform errors. Errors in the range E1xxx represent request errors. Errors in the range E2xxx represent tenant configuration errors.