ReadiNow allows you to integrate your tenant data with other systems. You can query and update data from outside the platform by exposing your data through Record APIs.
Authentication
The platform's APIs use OAuth 2.0 authentication with the Client Credentials Grant Flow, which generates a token from a client identifier and a shared secret.
Client and Secret Configuration
To obtain an access token for the platform's APIs, it is necessary to create a Client Identifier and a Shared Secret. Each Client Id is linked to a user account, and access tokens issued against this client Id will cause API operations to be performed in the context of this user account. It is security best practice that a new account is created for each integration, as well as a new OAuth Client definition; in this way it is easy to identify the origin of requests and disable one integration without affecting others.
This configuration is done in Administration > Integration > OAuth Clients.
New OAuth Clients configuration in Integration
Step 1: Creating a new client
Select +NEW and the following dialogue appears, where the associated user account must be selected.
Select the associated User account and save
Once the user account is selected, select Save and the Client Id will be automatically generated and populated on the form.
The automatically-generated Client Id
Step 2: Creating a new secret
After the Client Id has been created, select +NEW under SECRETS; in the dialogue that appears simply select Save and a secret will be automatically generated. Secrets do not expire.
Creating a new secret
An automatically-generated secret
Requesting an Access Token
The Client Id and Client Secret can be used to generate a token; this step will usually be done in the calling software, but for clarity a tool such as Postman can be used, as shown below.
A POST method call to the token service will respond with the access token and validity period if successful, and an error message if unsuccessful.
The client_id, client_secret, scope and grant_type must be sent in the body of the POST using the "x-www-form-urlencoded" content-type. The URL for the token service is https://{domain}.readinow.com/sts/v1/{tenant}/connect/token , replacing "domain" and "tenant" as appropriate.
An example token response
Paste the Client Id and secret values from the previous steps, then request a token and copy the generated token.
Record Types
See the article on Record Types for information about how Objects and their Fields / Relationships are represented in Record APIs, as well as the difference between Preview and Published APIs.
Enabling Record APIs
Once you have created an OAuth Client, you can go to Administration > Integration > Record APIs, and you will be shown a list of Record Types (Objects) for which record APIs can be enabled.
To enable preview APIs for a record type, click the Enabled radio button for that record type.
You can also use the Application drop-down to filter the displayed record types by the Application (Solution) that defines them. Once you have selected an Application, you can also choose to enable Record APIs for all Record Types assigned to that Application by clicking the Enable Application button.
Once you have enabled record APIs, you can click on the name of the Record Type to view its details.
From this page, you can enable, disable, modify, and publish the APIs for this Record Type. You can also view documentation for your Record Type's available APIs.
Note - if your Object is not attached to a Solution, then it will not appear as a Record Type on the Record APIs page.
You can select the application that an Object is attached to via its properties window in the form builder:
Publishing Record APIs
When you are satisfied that your API is stable (i.e. is not likely to change) then you can publish it. It will then become available for use at a well-known URL which will not change unless you re-publish the API. Any changes made to the Preview API (i.e. the API form) after the API has been Published will not be reflected in the Published API until you publish it again.
Each time APIs are published for a Record Type, its Revision Number is incremented (so its path changes from "records/my-record-type/r1" to "records/my-record-type/r2", etc).
Sandbox (Swagger) Interface
A sandbox (Swagger UI) is available for the platform's public APIs. This UI provides documentation for each API and its operations, as well as a facility for invoking those operations.
Open a web browser and navigate to https://{domain}.readinow.com/api/swagger/{tenant}/index.html replacing "domain" and "tenant" with the appropriate values.
From the Select a spec drop-down, you can choose to view the documentation for either your Preview or your Published APIs.
Swagger interface
Click the Authorize button to enter the token (remember to first add "Bearer ")
With a valid token it is possible to execute any of the API methods directly in the Swagger interface; where parameters are required these can be entered in the Swagger interface.
Example of executing a method using the Try it out button