How to import records using the Neoserra RESTful JSON API module
The Neoserra RESTful JSON API refers to an architectural style for an application program interface (API) that uses HTTP requests to access data in your Neoserra database. That data can be used to GET, PUT and POST data types (DELETE is not supported), which refers to the reading, updating and creating of records.
The Neoserra RESTful API will accept JSON for request payload and also send responses in JSON. JSON stands for JavaScript Object Notation, and it is a lightweight format for storing and transporting data. It was derived from JavaScript, but many modern programming languages include code to generate and parse JSON-format data. Code for parsing and generating JSON data is readily available in many programming languages, such as Java, Perl, C# and many more. OutreachSystems does not provide custom programming services. In order to utilizde the Neoserra RESTful JSON API you will need to engage with a programmer who can perform the integration for you.
This is an optional module that can be activated in your database upon request. Once it is activated databases administrator will see a new menu option titled "Developer" with the JSON API menu item:
While testing, we strongly recommend that you initially create a "Sandbox" center to which you import your test records. This will avoid creating test records in your production centers.
User Accounts
Once the JSON API feature has been enabled in your database, not only will administrators see this new menu option, there will also be an added checkbox on the accounts record to allow certain users access to this menu option:
In other words, you don't have to be an administator to access the JSON API, but if you are not an administrator then the "Allow access to integration module management?" checkbox will need to be checked. Thus, a third-party programmer who will be implementing the solution for you, will need a user account to the Neoserra database with this checkbox enabled and the appropriate level of permissions to allow them to review the imported records. Keep in mind that you can limit their permissions to just those record types that they will be working on.
In addition to providing a user account to the respective party doing the implementation, we also recommend that you create a secondary "Service" account under which the Endpoint will actually be configured. Once the implementation has been completed the user account for the contractor can be inactivated, while the solution continues to run under the service account, which, by virtue of being a service account, has no login permissions. This ensures an added layer of security.
To create a "Service" account, you can go to Administration|Accounts and create a new USER account (you do not need to create a counselor record for this account):
Once you have created the user credentials, then on the Accounts page, make sure you select the Status: "Service" and set the permissions based upon the data you will be importing. For example, in the screenshot above, the service account will only be able to edit and add new client/contact records into the database. You will need to set the permissions to match the needs of your implementaion.
Setting up Endpoints
Once the service account has been created, you can use this account to create your Endpoint under Administration|Configuration|API:
Add the IP addresses of any computer that will be using the API. If left blank, then any computer on the Internet can conceivably connect to the API. However, even if someone were to try to connect, the caller must use the Access Key to be authenticated. Thus, specifying the source IPs of the API calls simply adds one more layer of protection.
API Documentation
The Neoserra RESTful JSON API documentation can be found under the Developer|JSON API menu option. The documentation is auto-generated based upon the configuration in your database. When the Neoserra database administrator adds a field, or changes a field from optional to mandatory (or vice versa) then this is instantly reflected in the documents. Neoserra does NOT maintain different versions of the documentation. It is important for all Neoserra database administrators to communicate with their integration team and let them know when a change is being made to the Neoserra data requirements.
Again, it should be noted that Neoserra does not determine compliance of the records being imported - it is the database administrator who determines the field requirements under the Administration|Configuration|Field Requirements menu option.
Audit Log
To eliminate confusion for API users when an error occurs, Neoserra will issue HTTP response codes that indicate what kind of error occurred. This gives maintainers of the API enough information to understand the problem that?s occurred. We don?t want errors to bring down our system, so we can leave them unhandled, which means that the API consumer has to handle them. Common error HTTP status codes include:
- 400 Bad Request - This means that client-side input fails validation.
- 401 Unauthorized - This means the user isn't not authorized to access a resource. It usually returns when the user isn't authenticated.
- 403 Forbidden - This means the user is authenticated, but it's not allowed to access a resource.
- 404 Not Found - This indicates that a resource is not found.
- 500 Internal server error - This is a generic server error. It probably shouldn't be thrown explicitly.
- 503 Service Unavailable - This indicates that something unexpected happened on server side (It can be anything like server overload, some parts of the system failed, etc.).
Rather than ignore repeated 4xx and 5xx status codes, you should ensure that you're correctly interacting with the API. For example, if an endpoint requests a string and you're passing it a numeric value, you're going to receive a 5xx validation error, and your call won't succeed. Similarly, attempting to access an unauthorized or nonexistent endpoint will result in a 4xx error.
Communication between client and server should be private which is why Neoserra always uses SSL/TLS.
Want more? Browse our extensive list of Neoserra FAQs.