Requests & Responses

All requests and responses use JSON encoding.

Requests

The URL path structure is based on the API mapping defined in FIMMAS. The HTTP methods used in the API are GET, POST, and PUT, each of which have a specific use case:

HTTP Method Description
GET GET requests are used to retrieve data and should not have any effect on the server.
POST POST requests are used to submit data to the server, often causing a change in state or side effects on the server.
PUT PUT requests are also used to submit data to the server, replacing the target resource with the request payload.

The recommended naming conventions of the FIMMAS Data Services API use both the HTTP methods and named resources to provide clues to what each API call does without the need to know the specific implementation details. For more information about the recommended requests, see the FIMMAS API specification. For information about how to customize requests, see the URL convention or FIMMAS API Mapping.

The JSON body of the POST and PUT requests should follow the structure outlined in the API specification. If additional information is provided, either in the JSON body or header information, the API will not be affected as long as the required values are present. Any other information will be ignored.

Responses

The FIMMAS Data Services API wraps all responses in a standard structure. The JSON response structure is composed of:

Name Data Type Description
DATA Array This is where all your data will be returned. The Contents will depend on which API Request was made.
EXCEPTIONS Array This is where any messages about the request will be returned. Messages could be errors, warnings, or informational.
RESPONSE Integer This is the HTTP status code. It will also be set as the HTTP response’s status code.
UUID String Used to uniquely identify each request/response, usually for use in paging and debugging.
SEQ Integer The sequence number of the response. The sequence number on paged responses is equal to the page number.
TOTPAGES Integer The total number of pages in the response.
FILE Object Used for document uploads and downloads. See File Handling for more details.

Example Response Structure

{
  "DATA": [],
  "EXCEPTIONS": [],
  "RESPONSE": 200,
  "UUID": "450b5f90-c94d-4991-b452-7a46f0a31f42",
  "SEQ": 1,
  "TOTPAGES": 2,
  "FILE": {
    "DATA": "",
    "NAME": "",
    "TYPE": ""
  }
}