SOUP API Overview

The System Software Updates API is a RESTful API that enables to perform Create/Read/Delete operations for SOUP-related resources such as tags, systems, or recipes etc.

The APIs supports JSON payload with Hypermedia. You can traverse across resources via cursor based pagination. Furthermore the Management API provides role based access control based on standard roles.

The System Software Updates API is split into two sections, depending on the use case.

Management API

The Management API is an user-facing API for managing and listing content. It allows you to:

READ and DELETE systems
READ and DELETE modules
READ, CREATE and DELETE recipes
READ and CREATE recipe-tags
READ, CREATE and DELETE recipe signatures
Trigger recipe validation
Traverse through recipe lifecycle

Install API

The Install API is a device facing API exposing recipes and software to be installed on systems. It allows the device to:

READ recipes
CREATE system reports
CREATE update reports
READ software artifacts
READ tags

Service API

The Service API is a user-facing API for retrieving information about the service itself. It allows you to:

READ service version
READ change-log

Rate limiting

The SOUP API has rate limits for read and write (i.e. create, update, delete) request per access token. Calls exceeding the given rate limit will be returned with HTTP 429 - Too many requests.

Operation	Rate limit per access token
GET	1.000 requests per minute
POST, PUT, DELETE	100 requests per minute

Cursor-based pagination

All SOUP API collections support cursor-based pagination. If a request's results exceed the maximum retrievable items per request, a cursor is provided in the response to fetch the next page of results. The cursor acts as a pointer to a specific position within the complete result set. The size parameter controls the number of items requested per page. The maximum allowed value for size is 500.

Filtering parameters are accepted only in the initial GET request. Subsequent requests for paginated results should utilize the cursor parameter (and optionally the size parameter). The initial GET request's response includes a totalElements field (equivalent to a count), indicating the total number of items matching the provided resource and filter criteria at the time of the request. This totalElements value is encoded within the returned cursor. Pagination is performed using the cursor. The size parameter allows controlling the number of items returned per request.

The totalElements value is calculated only during the initial request and remains constant for all subsequent requests using the same cursor. This means that the reported total count will not reflect any changes to the underlying data (e.g., new item creation or deletion) after the initial request. To refresh the totalElements count and reflect changes in the underlying data, a new initial GET request with the original filter parameters must be issued to obtain a fresh cursor.

Example

This is the response to the initial request to a cursor-based resource collection. The encoded cursor is provided as part of the _links.next.href to retrieve the next page. Information about the current page and the total number of elements is found in the page.size and page.totalElements fields.

// GET https://system-management.eu1.bosch-iot-rollouts.com/api/service/v1/changelog?size=1
{
  "_embedded": {
    "items": [
      {...}
    ]
  },
  "_links": {
    "next": {
      "href": "https://system-management.eu1.bosch-iot-rollouts.com/api/service/v1/changelog?size=1&cursor=oax8zWi6z2hhA-TVD8yovuKjkFw3XI6W6jMH8h_pnc9tbxF0AY41aU1OBqQ3AjenxWTXHyuJnCF11VYYmNDHNKiXHf6oGj24SlaBDTpRyyFtg5IY0bcCOg1ghh2emC4dDHEJTomthSFR_piD4yKKVKd9afBjCZLnZNWb23TEWigctRqrK9zftMuL"
    },
    "self": {
      "href": "https://system-management.eu1.bosch-iot-rollouts.com/api/service/v1/changelog?size=1"
    }
  },
  "page": {
    "size": 1,
    "totalElements": 333
  }
}

Subsequent calls then make use of the encoded cursor:

// GET https://system-management.eu1.bosch-iot-rollouts.com/api/service/v1/changelog?size=1&cursor=oax8zWi6z2hhA-TVD8yovuKjkFw3XI6W6jMH8h_pnc9tbxF0AY41aU1OBqQ3AjenxWTXHyuJnCF11VYYmNDHNKiXHf6oGj24SlaBDTpRyyFtg5IY0bcCOg1ghh2emC4dDHEJTomthSFR_piD4yKKVKd9afBjCZLnZNWb23TEWigctRqrK9zftMuL
{
  "_embedded": {
    "items": [
      {...}
    ]
  },
  "_links": {
    "next": {
      "href": "https://system-management.eu1.bosch-iot-rollouts.com/api/service/v1/changelog?size=1&cursor=oax8zWi6z2hhA-TVD8yovuKjkFw3XI6W6jMH8h_pnc9nbxB9AY4yaUxPBqQ3AjenxWTXPymOtCs0y0gAooa2NKiXHf6oGj24SlaBDTpRyyFtg5IS0bcCOwBghh3JzSxHWXUNTomthSFR_piD4yKKVKd9afBjCZLnZNXc2yXQzsg5unJaABoMSmze"
    },
    "self": {
      "href": "https://system-management.eu1.bosch-iot-rollouts.com/api/service/v1/changelog?size=1&cursor=oax8zWi6z2hhA-TVD8yovuKjkFw3XI6W6jMH8h_pnc9tbxF0AY41aU1OBqQ3AjenxWTXHyuJnCF11VYYmNDHNKiXHf6oGj24SlaBDTpRyyFtg5IY0bcCOg1ghh2emC4dDHEJTomthSFR_piD4yKKVKd9afBjCZLnZNWb23TEWigctRqrK9zftMuL"
    },
    "previous": {
      "href": "https://system-management.eu1.bosch-iot-rollouts.com/api/service/v1/changelog?size=1&cursor=oax8zWi6z2hhA-TVD8yovuKjkFw3XI6W6jMH8h_pnc9nbxB9AY4yaUxPBqQ3AjenxWTXPymOtCs0y0gAooa2NKiXHf6oGj24SlaBDTpRyyFtg5IS0bcCOwBghh3JzSxHWXUNTomthSFR_piD4yKKVKd9afB9Ho_lD-fnJoIpMAGyvSVYBYK0DeJThctUYQ"
    }
  },
  "page": {
    "size": 1,
    "totalElements": 333
  }
}