Response Data and Format

Our company provides a wide range of APIs, accessible through a central gateway. The importance of a unified structure and language is further amplified by this. A consistent response structure across all APIs not only simplifies usage and integration for developers but also promotes seamless interoperability between different services and platforms.

To ensure the highest level of consistency in the language and structure of our APIs, we aim to establish clear guidelines that can be applied across all endpoints and functions. This includes standardizing data types, using uniform naming conventions, and implementing recurring structures in response data. With this approach to designing response data, we strengthen the foundation of our API architecture and set a high standard for the quality and user-friendliness of our services.

Standardized Response Structure

Each response from our APIs must (MUST) have a standardized structure to ensure consistency across different endpoints. This includes the consistent use of objects and fields in the response.

Example:

{
  "data": { ... },
  "meta": { ... }
}

• data (MUST): Contains the main data of the response. This can be a single object or an array of objects, depending on the request.
• meta (SHOULD): Should include metadata about the response, such as pagination information and other relevant details.

Use of JSON as the Primary Data Format

The primary format for response data must (MUST) be JSON (application/json), unless specific use cases require an alternative format. JSON is easy to use and widely adopted, facilitating integration across various platforms and programming languages.

Each JSON-based message must (MUST) adhere to the following rules:

• All JSON field names must (MUST) follow naming conventions (camelCase, American English, etc.).
• Field names must (MUST) contain ASCII alphanumeric characters, underscores (_), or dollar signs ($).
• Boolean fields must (MUST) not have a null value.
• Fields with a null value should (SHOULD) be omitted.
• Empty arrays and objects should (SHOULD) not be null; use [] or instead.
• Array field names should (SHOULD) be plural (e.g., "orders": []).

Pagination and Filtering of Results

Responses that return data collections must (MUST) support pagination to limit the amount of data transferred and to minimize network resource load.

Additionally, the response must (MUST) include metadata to help the client interpret the results. The actual data should be returned in an array under the data field, not at the top level of the response.

Example: GET /bikes

{
  "data": [
    // Array of returned items
  ],
  "meta": {
    "page": 1,
    "nextPage": 2,
    "previousPage": null,
    "perPage": 10,
    "sortBy": "price",
    "order": "asc",
    "totalCount": 100
  }
}

Field Selection (Sparse Fieldsets)

To reduce response size and improve efficiency, APIs optional SHOULD support sparse fieldsets using the fields query parameter. This allows clients to request only specific top-level fields from the data object.

Example of an API Request with the fields Parameter:

GET /api/v1/employers/{id}?fields=companyData,contactPerson

• The fields parameter MUST be a comma-separated list of top-level fields from the data object.
• If fields is omitted, the full data object MUST be returned.
• Nested field access (e.g., fields=companyData.name) is NOT supported.
• Invalid field names MAY be ignored or SHOULD return a 400 Bad Request.

Example of a Response:

{
  "data": {
    "companyData": {
      "name": "Example GmbH"
    },
    "contactPerson": {
      "name": "Max Mustermann"
    }
  },
  "meta": {
    "requestId": "abc-123",
    "timestamp": "2025-06-26T15:30:00Z" 
  }
}