Stibo Systems STEP API

API specification summary

STEP REST API V2
Version: 1.0.0

About

The STEP REST API V2 provides read and write access to a set of core STEP objects using the standard HTTP operations GET, PUT, POST and DELETE.

Resource Representation

With the exception of two resource operations for retrieving and replacing asset content (binary data) all request and response bodies are JSON, compliant with the schema documented here.

Context and Workspace

All requests are handled in a specific STEP context and workspace and both can be specified via query parameters available for all resource operations. A context must always be specified while requests per default will be handled in the "Main" workspace.

Polymorphism

In STEP, attributes, reference types and data container types can all be either single- or multivalued. The STEP REST API V2 uses polymorphism to address this complexity with resources that include values, references and data containers specified to produce and consume a common "abstract" supertype that always will be one of either the single- or multivalued subtype.
As an example, the GET /entities/{id}/values/{attributeId} resource operation is specified to return a "Value" but as evident from the model, the "Value" will always be "oneOf" either "SingleValue", that has a "value" property for which the value is an object, or "MultiValue", that has a "values" property for which the value is an array.
Clients are advised to use the presence or absence of the plural array property ("values", "references" and "dataContainers") to determine the concrete type.

Authentication

In the current release, the only supported authentication option is Basic Authentication. With Basic Authentication, user name and password are supplied with each request and it is therefore highly recommended to only use the API in conjunction with HTTPS.

Versioning

The STEP REST API V2 is versioned using semantic versioning. Stibo Systems reserve the right to make non-breaking, minor / patch changes in any release without warning and clients must be coded / configured to be 'tolerant' and capable of handling such changes.

Examples of breaking, major changes:

• Renaming of a property
• Removal of a property
• Property type change
• Addition of new property required for write operations
• Marking existing property as required for write operations
• Removal of resource or resource operation
• Materially different behavior for existing resource operation

Examples of non-breaking, minor / patch changes:

• Addition of new properties in request responses
• Addition of new query parameter not required for write operations
• Addition of new resource or resource operation
• Bug fixes that do not change the schema or resource operations as described here
• Inclusion of a response body for resource operations specified to return a 200 response with no body
• Change of response "Model" / "schema" to type extending the previously specified type
• Renaming a "Model" / "schema" type
• In addition, error message texts may change without warning within the same version.
• Client program logic should not depend upon the message content.

Error Handling

The STEP REST API V2 responds with standard HTTP status codes, with 2 responses indicating a success, 4 responses indicating a client error and 5** indicating a server error. Notice that this specification does not specify common error responses like 500 (internal server error) or 401 (unauthorized) for the individual resource operations. Clients should however be capable of handling such responses.

Error responses have a JSON response body (see Error schema below) containing HTTP status code information in addition to a message providing details about the error. As mentioned above, client program logic should not depend upon the message content.

The specific status codes used in the API are:

• 200 (OK): Success, response may or may not have a body
• 201 (Created): Entity successfully created, response may or may not have a body
• 400 (Bad request): The server cannot or will not process the request due to an apparent client error
• 401 (Unauthorized): Returned only in relation to failed authentication
• 404 (Not Found): Returned only in relation to objects specified via path parameters (variable parts of the URL). If STEP objects referenced in request bodies or via query parameters cannot be found, the response will be 400.
• 429 (Too Many Requests): Clients are per default limited to 100 requests per second. Returned if the rate limit is exceeded.
• 500 (Internal Server Error): Unexpected error (could potentially cover an issue that rightfully should be a 400)