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
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.
Verb | Description |
---|---|
GET |
Used for retrieving resources. |
POST |
Used for creating resources, or performing custom actions (such as copying an existing resource). |
PUT |
Used for replacing resources or collections. |
PATCH |
Used for updating resources with partial JSON data. For instance, a Folder resource has a description and closed attribute. A PATCH request may accept one or more of the attributes to update the resource. |
DELETE |
Used for deleting resources. |
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:
Attribute | Description |
---|---|
page | current page of resources |
pages | total number of pages for all resources |
count | total number of object in items |
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
)