API Overview

The MachineShop API is designed to make it easy for developers to create applications using a REST API to represent connected things and other, aggregated APIs. As with all REST APIs, each request is atomic - there is no session. Request signatures generally follow a resource-based convention:

  • List: GET /resource
  • Retrieve: GET /resource/{id}
  • Create: POST /resource
  • Update: PUT /resource/{id}
  • Destroy: DELETE /resource/{id}

Resources

The MachineShop API is designed to make it easy for developers to create applications using a REST API to represent connected things and other, aggregated APIs. As with all REST APIs, each request is atomic — there is no session. Request signatures generally follow a resource-based convention:

  • List: GET /resource
  • Retrieve: GET /resource/{id}
  • Create: POST /resource
  • Update: PUT /resource/{id}
  • Destroy: DELETE /resource/{id}

All of the individual resources and their associated REST endpoints are documented under API Docs.

API Token

You’ll need an API token to use the MachineShop APIs. If you’re reading this, you’ve already logged into the developer portal. Your API token can be found TODO: update to new location within your profile. You can also make an API call to retrieve your profile information with your email and password:

URL:

POST /services.machineshop.io/api/v1/platform/user/authenticate

Headers:

Accept: application/json
Content-Type: application/json

Body:

{
  "email": "you@example.com",
  "password": "yourpassword"
}

The returned JSON will be your profile information including your authentication_token.

Request Headers

All MachineShop APIs consume and produce JSON (application/json MIME type). Nearly all APIs also require user authentication (7013511173 — see below). The following header rules therefore apply:

  1. All requests must include:

​ Accept: application/json

  1. Requests with a body (e.g., POST, PUT) must also include:

​ Content-Type: application/json

  1. Endpoints requiring authentication (all except user authenticate and device report POST endpoints) must also include:

​ Authorization: Basic [base64_encode(your auth token concatenated with ":X")]

The Authorization header can also be automatically generated for each request when using the “Try it out” feature within the developer portal.

Query String Operators

All GET requests to the MachineShop API have the ability to query specific fields on the underlying data. For example, if you’re looking for a specific Data Source Type, you could make a request that looks something like:

GET .../data_source_types?manufacturer=Acme&model=Dynamite1000

You also have the ability to use basic logical operators on the query string. For example, if you wanted to look for all Data Sources created since the first of March 2015, you could do something like this:

GET .../data_sources?created_at_gt=2015-03-01

All logical operators are appended to the field on which they are being applied. Keep in mind that the query string will only look at the last occurrence of a key pair when a key appears more than once. For the case that you need a values between two thresholds, we’ve included the _between operator that takes two arguments separated by an underscore. Below is a complete list of operators.

Operator Equivalent
_gt >
_gte >=
_lt <
_lte <=
_between <= x <=
_like Substring search similar to SQL LIKE ‘%value%’

Paging

All GET requests that return multiple results are paged. Paging defaults to 20 per page. If you wish to retrieve pages beyond the first page or have more results returned per page, you can use the query string parameters page and per_page like this:

GET .../data_sources?page=2&per_page=50

Listing requests like above return an array of objects by default. Sometimes it’s helpful to know more about the big picture when it comes to paging…How many pages are there? How many total resources are there?…This can be achieved using the page_meta query string parameter. When set to true a JSON object, rather than an array, will be returned. The object will contain several keys indicating paging metadata and an array call resources that would be the normal default return.

GET .../data_sources?page_meta=true

Returns:

{
  "page": 1,
  "per_page": 20,
  "total": 26,
  "resources": [
    { ... },
    { ... },
   ...
  ]
}

In

All GET requests have the ability to use the query parameter in. The in query parameter behaves similarly to the IN SQL operator. When using the in query parameter, the requester must distinguish which field in the resource that the requester would like to search. The requester can then separate multiple input values with a comma. For example:

GET .../platform/data_sources?make_in=samsung,sony,lq

Returns all records that have a make of samsung sony or lg

Sorting

All GET requests that return multiple results may be ordered by a field. Results are typically returned in the order they persisted: oldest first. Reports are returned newest first. To change the order of the results, you can use the query string parameter order_by:

GET .../data_sources?order_by=name

Listing requests like above return an array of objects sorted by the name field in ascending order. To sort in descending order, negate the field name like below:

GET .../data_sources?order_by=-name

You may order by any field on the document but please note that not all fields are indexed in the database. So some fields may cause the response to take longer than others.

Arbitrary Data Storage

All entities in the MachineShop platform have a minimum schema. However, the schema is flexible insofar as arbitrary key-value pairs may be added to them as seen fit by an application developer. Keep in mind that this is purely convenience for storage and retrieval. Any validation must be accomplished in the client application.