Quickstart

This section gives an introduction about senaite.jsonapi. It assumes you have SENAITE LIMS and senaite.jsonapi already installed. The JSON API is therefore located at http://localhost:8080/senaite/@@API/senaite/v1. Make sure your SENAITE LIMS instance is located on the same URL, so you can directly click on the links within the examples.

All the coming examples are executed directly in Google Chrome. JSONView_ is used to beautify the generated JSON and the Advanced Rest Client Application to send POST requests to senaite.jsonapi. See Installation for details.

Version route

The version route prints out the current version of senaite.jsonapi.

http://localhost:8080/senaite/@@API/senaite/v1/version

{
    url: "http://localhost:8080/senaite/@@API/senaite/v1/version",
    date: "2020-03-03",
    version: "1.2.2",
    _runtime: 0.0036830902099609375
}

Note

The runtime indicates the time spent in milliseconds until the response is prepared.

Content Routes

senaite.jsonapi allows you to directly retrieve contents by their portal_type name. These Resources are automatically generated for all available content types in SENAITE.

Each content route is located at the Base URL, e.g.

The name of each of these content routes is transformed to lower case, so it is also perfectly ok to call these Resources like so:

For instance, calling a content route like

will return a JSON containing records of type Client only:

{
    count: 1596,
    pagesize: 25,
    items: [
        {
            uid: "ffce0bba48204c63a62b0744a6b762bf",
            id: "client1",
            ...
            portal_type: "Client",
            ...
        },
        {},
        {},
        ...
    ],
    page: 1,
    _runtime: 0.09960794448852539,
    next: "http://localhost:8080/senaite/@@API/senaite/v1/client?b_start=25",
    pages: 64,
    previous: null
}

Some examples of searches for SENAITE-specific portal types below:

Check out senaite.core’s types.xml for the full list of portal types that come with SENAITE LIMS by default. Keep in mind that senaite.jsonapi will also handle other portal types that might be registered by other add-ons. For instance, SENAITE Health, an extension for health-care labs registers a new portal type named Patient. If you have this add-on installed, the url http://locahost:8080/senaite/@@API/senaite/v1/patient will work as well, returning the list of objects from type Patient.

From the JSON response above, note the following:

The Response Format in senaite.jsonapi content URLs is always the same. The top level keys (data after the first {) are meta information about the gathered data.

The items list will contain the list of results. Each result is a record with just the metadata available in the catalog. Therefore, no object is “waked up” at this stage. This is because of the APIs two step concept, which postpones expensive operations, until the user really wants it.

All items are batched to increase performance of the API. The count number returns the total number objects found, while the page number returns the number of pages in the batch, which can be navigated with the next and previous links.

Get records full data

To get all data from an object, you can either add the complete=True parameter, or you can request the data with the object UID.

The requested content(s) is now loaded by the API and all fields are gathered.

Note

Please keep in mind that large data sets with the ?complete=True Parameter might increase the loading time significantly.

UID Route

To fetch the full data of an object immediately, it is also possible to append the UID of the object directly on the root URL of the API, e.g.:

Note

The given UID might seem different on your machine.

The response will give the data in the root of the JSON data, so only the object metadata is returned, e.g.:

{
    expirationDate: "2019-05-02T11:53:13+02:00",
    _runtime: 0.03150486946105957,
    exclude_from_nav: null,
    BankBranch: null,
    Fax: null,
    title: "Happy Hills",
    parent_id: "clients",
    location: null,
    parent_url: "http://localhost:8080/senaite/@@API/senaite/v1/clientfolder/b7e8d2288af74092afe0cf3a0e172f87",
    PhysicalAddress: {
        city: "Barcelona",
        district: "",
        zip: "",
        country: "Spain",
        state: "Catalonia",
        address: ""
    },
    portal_type: "Client",
    AccountName: null,
    language: "en",
    BulkDiscount: null,
    parent_uid: "b7e8d2288af74092afe0cf3a0e172f87",
    parent_path: "/senaite/clients",
    rights: null,
    AccountNumber: null,
    modified: "2019-07-24T23:14:57+02:00",
    EmailAddress: null,
    BillingAddress: {
        city: "",
        district: "",
        zip: "",
        country: "",
        state: "",
        address: ""
    },
    ...
}