REST API Guidelines¶
Version: 2.4.0
Last Changed: February 27, 2025 (see changelog)
Scope¶
These are REST API design guidelines RECOMMENDED for all Siemens developers working on internal and external APIs, as well as for our customers, partners, and anyone consuming or working with our APIs.
These guidelines MUST be applied to Siemens Xcelerator X products and solutions. Project teams MAY enhance these guidelines with additional restrictions based on their business needs, but we generally recommend that the guidelines listed here are still adhered to.
The goal of these guidelines is to help developers design simple, consistent, and easy-to-use APIs that can be easily consumed by API clients. An API provider can focus on quickly providing value while avoiding the headache of trying to solve common API design or system integration problems.
Conventions Used in These Guidelines¶
These guidelines use consistent and standardized language that unambiguously describe each requirement. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14, RFC2119 and RFC8174 when, and only when, they appear in all capitals, as shown here.
| Key Word | Alternative Terms | Definition |
|---|---|---|
| MUST | "REQUIRED", "SHALL" | This word means that the definition is an absolute requirement of the specification. |
| MUST NOT | "SHALL NOT" | This phrase means that the definition is an absolute prohibition of the specification. |
| SHOULD | "RECOMMENDED" | This word means that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course. |
| SHOULD NOT | "NOT RECOMMENDED" | This phrase means that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label. |
| MAY | "OPTIONAL" | This word means that an item is truly optional. One may choose to include the item because it is required or because it enhances the product while another may omit the same item. An implementation which does not include a particular option MUST be prepared to interoperate with another implementation which does include the option, though perhaps with reduced functionality. In the same vein this also applies vice versa. |
Interpreting the Rules¶
Guidelines in this document are organized in a hierarchy of rules. The hierarchical structure of rules make it easier to follow the ruleset.
Adherence to Recommendations and Best Practices
This document offers recommendations and best practices around the design of RESTful APIs. While most recommendations herein are optional, an API MUST adhere to the semantics described in this document when a specific recommendation is implemented.
The guidelines are organized hierarchically to present rules as combinatorial decision tree. Child rules MUST be considered if the parent rule is adopted. This combination allows the freedom to group rules and selectively enforce them if a dedicated feature for an API is selected and realized.
The following visualization demonstrates the deriving severity of rules.
Application of Rule Severity
This example illustrates an API that can optionally support sorting functionality. Although this functionality is optional, the API MUST adhere to all child rules if this feature is implemented. In other words, if your API provides sorting functionality, it must include a sort query parameter.
API MAY provide sorting of collections in response¶
...
Parameter sort in request MUST specify sort fields¶
...
Unique Rule Identifiers¶
Each rule is tagged with a unique identifier. This identifier can be used when referencing these guidelines from other documents.
A rule identifier has the format x or x.y, where x is the main rule id and y is the sub rule id. The main rule id x is unique across this entire document. The sub rule id y is unique within the parent rule.
Unique id range reserved for Main rule per guideline type:
- Media Type: 100 to 199
- Versioning: 200 to 299
- Error: 300 to 399
- Filtering: 400 to 499
- Sparse Fieldsets: 500 to 599
- Pagination: 600 to 699
- Sorting: 700 to 799
- Common Operations: 800 to 899
- Bulk Operations: 900 to 999
- Placeholder design guideline B: 1000 to 1099
Unique id range reserved for sub rule with in Main rule:
- Sub rule: 1 to 50
Example sorting guideline with unique id
API MAY provide sorting of Collections in Response [700]¶
Rule description.
Parameter sort in request MUST specify sort fields [700.1]¶
Rule description.
API MAY support sorting by more than one sort field in one request [700.2]¶
Rule description.
API MAY support defining the sort order for each sort field individually [700.3]¶
Rule description.
Sort order MUST be defined for each sort field individually [700.3.1]¶
Rule description.
Deprecated / Removed¶
API MAY support defining the sort order for each sort field individually [700.4]¶
Rule description.
JSON:API and Backward Compatibility to Version 1.1¶
The release of the API guidelines v1.2.0 removed all REST-specific rules which were based on the JSON:API guidelines.
Version 2.0.0 of the API guidelines adopted elements of the JSON:API guidelines while also incorporating feedback collected from v1.1.0. We collaborated across business units on a set of reasonable and feasible API guidelines that can be implemented with minimal effort across Siemens projects.
In addition to providing best practices for developing new APIs, the latest guidelines also provide guidance on how to incorporate these guidelines to well-designed legacy APIs and become compliant with Siemens Xcelerator REST API guidelines.
The latest guidelines are inspired by JSON:API and Zalando REST guidelines that let you choose and adapt the rules that are applicable to your business use cases. We have selected and combined them in a way to create a Siemens style for our API guideline.
APIs compliant with JSON API are backward compatible with these guidelines.
The API guidelines suggest applying breaking rules only on the keyword SHOULD. Hence, the latest guidelines recommend solutions other than JSON:API. However, you can still refer to JSON:API as a base for your API development along with the latest API guidelines. API clients built around JSON:API are able to take advantage of its features to become compliant with the current version of the REST API Design Guidelines.