Overview

Overview

The API is currently in Beta and available to all paying InspectAll subscribers. Use of the API complies with the terms set forth in the Master Subscription Agreement.

This describes a general overview of the InspectAll API. If you have any questions, please direct them to support@inspectall.com

• Schema
• HTTP Verbs
• Client Errors
• Authentication
• Pagination
• OData Filtering and Ordering

Schema

Current Version

There is one version of the InspectAll API: v1. You can request a specific version via the url used for the endpoint.

All API access is over HTTPS, and accessed from

https://api.inspectall.com/v1/

For example, the /assets API call is reachable at https://api.inspectall.com/v1/assets. All data is sent and received as JSON.

Development Environment

The testing and development environment can be accessed from:

https://api-dev.inspectall.com/v1/

This environment is updated occasionally and any data there will be overwritten or wiped periodically.

Blank Fields

Blank fields are included as null instead of being omitted.

Timestamps

All timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:mm:ss.SSSZ

Content-Type

All Requests and Responses should contain the following in the headers:

Content-Type: application/json

HTTP Verbs

Where possible, our API strives to use appropriate HTTP verbs for each action.

Client Errors

Sending invalid fields will result in a 422 Unprocessable Entity response.

Invalid: Error Response Format

{
   "errors": {
     "description": ["is too long (max 500 characters)"],
     "folderId": ["is required"]
   }
}

During some DELETE requests, the server will respond with a 412 Precondition Failed. The body will include a confirmation object with the additional resources the delete will modify. The delete will not be processed until it is confirmed.

Delete: Precondition Failed Format

{
    "formsCount": 45
}

Authentication

This is an HTTPS-only API. Authentication is based on API Keys. Each API Key is associated with an InspectAll user. Results returned from some responses are based upon the roles and teams of the user to which the API key is tied.

The API Key is passed via HTTP Basic Authentication and goes in the username field. A dummy password, such as X, goes in the password field.

To try the API via curl on the command-line, the general format would be:

Basic Authentication curl -u API_KEY:DUMMY_PASSWORD API_URL

For example, if your API key is a1b3c3, you would execute:

curl -u a1b3c3:X https://api.inspectall.com/v1/accounts

Authenticating with invalid credentials will return 401 Unauthorized

Pagination

Requests that return multiple items will be paginated to 50 items by default. You can specify further pages with the ?page parameter. For some resources, you can also set a custom page size with the ?per_page parameter.

Note that page numbering is 1-based and that omitting the ?page parameter will return the first page.

The pagination meta-data has the following attributes:

Example

  "page": 1,
  "pages": 2,
  "count": 52,
  "items": [
    // item objects listed here
  ]

To utilize pagination meta-data, simply pass in the desired page you would like to display as a parameter.

Parameters

  https://api.inspectall.com/v1/assets?page=3

OData Filtering and Ordering

For filtering result sets and ordering of objects, we use the OData standard.

For any attribute returned on an object, we can use the OData $filter option to specify a value to filter our requested resources against. For example, if a folder object contains a boolean attribute closed and we want to only return folders that match the filter of closed=true, then we specify the corresponding OData $filter attribute. This will return us a result set of only closed folders:

$filter=(closed eq true)

Likewise, for ordering of results, we can order against an attribute returned on the object with the $orderby option.

So, if we have a date attribute of createdAt that we might want to sort in descending order, we would pass the option:

$orderby=createdAt desc

These OData options ONLY apply to filtering and ordering result sets based on an attribute the returned object posseses. They will be identified in the Parameters section of our GET endpoints with oData followed by an example.

Apart from oData filters, our endpoints also include normal query string parameters that you would expect to see in a RESTful API. These are identified under the Parameters section of our GET endpoints without the (oData) identifier, and should be treated as such.

Note: As with any request being sent, all URL data must be URL Encoded. (eg. $filter would be %24filter)