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

Input validation

The SOUP API has the following restrictions for inputs.

Generally there are validations for text, ID, and version

ID: ^[a-zA-Z0-9]{12}+$
Text: ^[a-zA-Z0-9À-ÿ\u0027`´&\-+=#€¥\$%.;,:!()\[\]_ ]+$
Version: ^[a-zA-Z0-9\._\-]+$

Entity	Property	Validation regex
Recipe	id	ID
Recipe	name	Text
Recipe	description	Text
Recipe	version	Version
Recipe	approvalRemark	Text
Recipe	stateRemark	Text
Module update definition	moduleQuery	`^attribute\.[a-zA-Z0-9\.\-=;, _\$€¥]+$`
Module update definition	moduleCountQuery	`^count(=gt=\|=lt=\|==\|=ge=\|=le=)\d+$`
Module update definition	name	Text
Module update definition	description	Text
System distribution set	name	Text
System distribution set	description	Text
Signature	name	Text
Signature	description	Text
Recipe tag	id	ID
Recipe tag	name	Text
Meta data	key	Text
Meta data	value	Text

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
  }
}

Re-try and re-connect guidelines

Your systems and applications interacting with any of our APIs need to be able to bridge small interruptions or latencies. On the one hand, this requirement is imposed by the fact that we work with distributed systems, where short interruptions can result from a networking issue, a maintenance activity, or a service incident. On the other hand, your devices and application will also highly depend on the network services of other providers and should not break in case they are not able to keep connections with our infrastructure; at least for short time.

In order to be able to identify cases where your request might not have reached our service, we recommend orienting on the exception you might receive upon request. The status code returned by the SOUP service might help to indicate whether the failure is transient or not.

The following HTTP status codes typically indicate that a re-try is appropriate:

429 Too Many Requests
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout

No matter whether you request our service via the Management, Install, or Service API, in case of exceptions we provide the same status codes.

All usage of our APIs should apply a systematic approach for managing re-tries incl. an exponential back-off, as well as re-connects. This helps to avoid unnecessary load, that can become counterproductive.