-
Notifications
You must be signed in to change notification settings - Fork 0
JSend ‐ Json Message Structure Overview
Like many modern API endpoints, FlexV2 API returns data in the ubiquitous JSON structure. In developing FlexV2, it was important that we develop an API that returned data in a consistent manner for ease of consumption and our end users peace of mind. To that end, the development team decided to use a somewhat common JSend message structure as our medium of choice.
[TOC]
The Flex API has a standard format of JSON responses. Each API response will have the following parts:
{
"status": "{ success | fail | error }",
"data": "{ a wrapper for any data to be returned }"
}Please note that the appropriate HTTP status codes will be returned with the JSON responses depending on the situation. (HTTP 200, 400, 404, etc.)
The following example is of a call to get a list of Company records through the FlexV2 API
GET http://localhost/api/v2/companies
The resulting JSON response was as follows:
{
"pageNumber": 1,
"pageSize": 3,
"totalNumberOfPages": 1,
"totalNumberOfRecords": 2,
"status": "success",
"data": [
{
"address1": "12345 Adams Lane",
"city": "Addition ",
"country": "USA",
"name": "Software Security Experts Exchange",
"state": "TX",
"uniqueKey": 3,
"zipcode": "75254"
},
{
"address1": "12345 New Address",
"address2": "Suite 234",
"name": "Chess Enterprises",
"uniqueKey": 4
}
]
}Please note that the basic information "status" and "data" are present as part of the response. The additional metadata about the response (pageNumber, pageSize) is added only to keep track of paged requests.
The following example is of a failed Company API request. In this case, the company number does not exist, so is expected to fail.
GET http://localhost/api/v2/companies/11
{
"status": "fail",
"data": "Unable to locate members record with the unique key of 11"
}The following example is of an API action that has errored when attempting a company delete.
DELETE http://localhost/api/v2/companies/11
{
"status": "error",
"message": "Could not delete company record with the unique key of 11 due to the following error: System.Exception: Unexpected delete error."
}Note that no data was returned and a detailed message is provided so that the API user may address the issue.
Paging is based on the JSend Success pattern. It includes additional fields to help navigate and determine page sizes and number of records.
{
"pageNumber": 2,
"pageSize": 10,
"totalNumberOfPages": 158,
"totalNumberOfRecords": 1577,
"nextPageUrl": "http://localhost/api/v2/hardware/event/descriptions?page=3&pageSize=10",
"previousPageUrl": "http://locahost/api/v2/hardware/event/descriptions?page=1&pageSize=10",
"status": "success",
"data": [
]
}