Responses

Siren

Almost all responses from the Freezerworks API will be returned as JSON and will follow the Siren specification. The benefit of that is three-fold. First, predictability. Your data is returned in a consistent format every time. Second, the format provides links to related content allowing for dynamic exploration of the API. And third, tooling and libraries exist to consume Siren data making developing against the API easier.

Here is a truncated example Siren response for the details of a User account:

  {
    "class": [
        "user"
    ],
    "title": "Details for a single User in Freezerworks.",
    "properties": {
        "active": true,
        "deleteAliquots": true,
        "modifyAliquots": true,
        "moveAliquots": true,
        "viewAliquots": true,
        "allowAccessViaAPI": true,
        "id": -8,
        "webPreferences": {
            "dateFormat": "YYYY-MM-DD"
        },
    },
    "links": [
        { "rel": [ "self" ], "href": "https://localhost/api/v1/users/-8" }
    ],
    "entities": [
        {
            "class": [ "group" ],
            "rel": [ "user" ],
            "properties": { "id": 6 },
            "links": [ { "rel": [ "self" ],
                    "href": "https://localhost/api/v1/groups/6" }
            ]
        },
        { "class": [ "role" ], "rel": [ "user-role" ],
            "properties": { "id": -8 },
            "links": [ { "rel": [ "self" ],
                    "href": "https://localhost/api/v1/roles/-8" }
            ]
        }
    ]
}

Error Responses

Error responses are also Siren formatted JSON. They will be returned with an appropriate HTTP status code (such as 400) and multiple errors may be returned at once.

Each error will contain a status code, an error code, and a message. They may also provide additional details as needed.

Here is an example error for an unknown User:

{
    "class": [ "error" ],
    "properties": {
        "errors": [
            {
                "status": 404,
                "error_code": "not_found",
                "message": "No matching records found.",
                "meta": {}
            }
        ]
    },
    "links": [
        { "rel": [ "self" ], "href": "https://localhost/api/v1/users/9000" }
    ]
}

Partial Responses and Pagination

Some end points may return a large number of records. In these cases the API may be configured to return a partial response. For instance, you wouldn't want to return all 4 million Aliquots at once. It would bog down the server and make for a very slow response. Instead, the API can send you a subset of the records at a time.

Instead of getting the standard HTTP status of 200, you will receive a 206 'Partial Content'. The Siren 'properties' object will tell you how many total records were found and how many were returned. It will also provide you a dataSetId so that you can retrieve the other records as needed.

The links Siren property will provide you links to get the next and/or previous subset of records if you need them. This makes it easy to process the data in chunks or request one page of data as it is needed.

Here is a truncated response showing that we returned 100 records of an available 34,554:

{
  "class": [
  "sample_collection"
],
  "title": "Samples in Freezerworks matching search criteria.",
  "properties": {
    "resultsTotal": 34554,
    "resultsReturned": 100,
    "dataSetId": "d3",
    "creationDateTime": "2023-03-07T17:17:18Z"
  },
  "links": [
        { "rel": [ "self" ],
            "href": "https://localhost/api/v1/samples?limit=100&offset=0&datasetid=d33"
        },
        { "rel": [ "prev" ], "href": "" },
        { "rel": [ "next" ],
            "href": "https://localhost/api/v1/samples?limit=100&offset=103&datasetid=d33"
        }
    ]
  }

Working With Non-Text Responses

Some endpoints return data that isn't text or contains elements that are textual representations of images or documents.

PDFs

The endpoints for printing labels and reports, for example, return PDFs which can then be saved or printed as needed. These are returned directly and are not part of a Siren formatted response. Although errors will be Siren formatted.

For endpoints that return PDFs look for the Content-Type header to be set to 'application/pdf' instead of 'application/json' and note that you will have a Content-Disposition header with the filename provided.

Embedded Images

Some endpoints include embedded images. For example, the details returned about a label format include a label preview. The embedded images are base64 encoded and must be decoded if you wish to display them.

To display the label preview image in an HTML document you might pull the encoded image value from the API request and use it like this:

  <img src="data:image/jpg;base64,/9j/4AAQS...AooooA//2Q==" >