Skip to main content

Request Data and Parameters

By applying standardized guidelines for path parameters, query parameters, header parameters, and the request body, we can ensure that our APIs are clearly structured, intuitively understandable, and predictable. Consistent handling of these elements not only simplifies the integration and use of APIs by developers and connection to third-party systems and services but also improves clarity within the Developer Portal.

Path-Parameters​

Path parameters are an essential part of the URL and serve to identify specific resources within the API. A consistent and clear approach to handling path parameters is critical for API usability and consistency.

Naming Criteria and Clarity​

Generic and Independent Identifiers (MUST): Path parameters must (MUST) be named in a way that clearly and unambiguously enables access to resources. The names should be generic and independent of specific products or use cases. It is essential that parameter names reflect the function and meaning of the data to make the API understandable and accurately represent resource data.

Use of kebab-case (MUST): Path parameters should (SHOULD) ideally be designed without separators to ensure maximum simplicity. If separators are necessary, they must (MUST) use kebab-case, as it improves readability and adheres to modern API design best practices.

Example:

Not recommended: GET /bikes/lease/12345 (The parameter 12345 is specific to this endpoint and ties the naming to a concrete product.)
Recommended: GET /leases/{leaseId} (The parameter {leaseId} is general and describes the identification of a lease agreement without specific product association.)

Query-Parameters​

Query parameters should (SHOULD) be used to filter API request results based on specific criteria. For example, contracts can be filtered by category, or leases by status. Additionally, sorting results by attributes such as price, date, or relevance should be supported. To manage large datasets, pagination parameters such as page and limit should be used.

Naming and Documentation​

Query parameters should (SHOULD) be descriptive and easy to understand. The naming of query parameters should (SHOULD) be consistent across all API endpoints. All available query parameters must (MUST) be documented in detail, including acceptable values and their effects on the results.

Formatting and Convention​

Query parameters must (MUST) be written in camelCase to ensure a consistent and readable format. Hyphens and underscores SHOULD be avoided as they can reduce readability and are inconsistent with modern REST conventions.

Standard Formats and Types​

Standardized formats must (MUST) be used for parameter values, such as ISO 8601 for dates (YYYY-MM-DD) and common sorting options like asc or desc.

Example for Query Parameters:

Filtering by attributes: GET /bikes?brand=Trek&color=blue – Filters bikes by brand and color.
Sorting: GET /bikes?sortBy=price&order=asc – Sorts bikes by price in ascending order.
Pagination: GET /bikes?page=2&perPage=20 – Displays the second page of bikes, with 20 entries per page.
Filtering leases: GET /leasing?startDate=2024-01-01&endDate=2024-12-31&status=active – Filters leases by date range and only shows active leases.

To simplify the widespread use of our APIs, the following standardized parameters for paging and sorting should be established.

Usage of Query Parameters in POST Routes​

In designing REST APIs, query parameters should be avoided in POST routes. Some clients and libraries may have difficulty handling query parameters in POST requests. Moreover, using query parameters in POST routes contradicts RESTful principles, where the request body is used for transmitting data. Instead, the request body should be used to send data in POST requests.

Pagination​

  • page: The page number to return. Pagination starts at 1. This parameter MUST be used to set the desired page of results.

    Example:

    GET /bikes?page=2

  • perPage: The number of entries per page. This parameter MUST be used to determine the number of entries per page.

    Example:

    GET /bikes?perPage=20

The response should (SHOULD) return the total count as totalCount, indicating the total number of available items, helping the client know how many pages there are in total.

Sorting​

  • sortBy: The field to sort by. Must be clearly and consistently named. This parameter MUST be used to set the sorting criteria.

    Example:

    GET /bikes?sortBy=price

  • order: The sort direction. Accepts asc for ascending and desc for descending. This parameter MUST be used to set the sort direction.

    Example:

    GET /bikes?order=asc

Example:

GET /bikes?page=2&perPage=20&sortBy=price&order=asc: This request returns the second page of bikes, each page containing 20 bikes, sorted by price in ascending order.

Header-Parameters​

Header parameters are essential for transmitting metadata and control information between client and server. They define methods for authentication, authorization, specifying content types, and many other purposes. Clear and consistent handling of header parameters is crucial to ensuring the functionality and security of the API.

Principles​

Standardized Header Parameters (MUST): The use of standardized HTTP headers, as defined in the HTTP specification, is mandatory. This includes headers like Content-Type, Accept, Authorization, and Cache-Control.

Proprietary Header Parameters (SHOULD): If new, specific requirements necessitate extending the standard headers, custom headers may be used. These should be clearly documented and given meaningful, distinctive names to indicate their proprietary nature. The "X-" prefix SHOULD not be used. Instead, purely proprietary headers MUST begin with the "JR-" prefix. Example: JR-Request-ID.

Key Header Parameters​

  • Content-Type (MUST): This header specifies the format of the request data. The most common value for RESTful APIs is application/json.

    Content-Type: application/json

  • Accept (MUST): This header specifies the response formats the client can accept. The value should include application/json to receive JSON data.

    Accept: application/json

  • Authorization (MUST): This header is used for transmitting authentication information. For APIs using OAuth 2.0, the format Bearer <token> should be used.

    Authorization: Bearer your_token_here

  • Cache-Control (MUST): This header controls the caching policies for the request/response. It must be used to indicate whether and how long the response may be cached. This is particularly important when working with a CDN. If no Cache-Control header is set, responses are not cached by default.

    Cache-Control: no-cache

  • If-None-Match (SHOULD): Using ETags in the request allows for optimizations in response handling, particularly to avoid unnecessary data transfers when resources have not changed.

    If-None-Match: "686897696a7c876b7e"

  • Location (SHOULD): Should be used when a new resource is successfully created (201 Created). The header contains the URI of the newly created resource and allows the client to access or further process it directly. A response body with resource data is allowed; however, the full URI MUST ONLY be returned in the Location header, not in the body.

    Location: /orders/123

Example of Proprietary Headers​

  • Request-ID (COULD): A custom header used for tracking and identifying requests across different systems. This facilitates debugging and monitoring.

    JR-Request-ID: 123e4567-e89b-12d3-a456-426614174000

Best Practices​

All header parameters used must (MUST) be clearly documented. This includes both standard and custom headers. The documentation should clearly describe the purpose of each header and the possible values. Redundant or unnecessary header parameters should (SHOULD) not be used. Every header should have a clear and necessary purpose. Security-related headers, such as Authorization and Strict-Transport-Security, must (MUST) be used to ensure the security of API communication.

Example:

GET /bikes?page=2&perPage=20&sortBy=price&order=asc HTTP/1.1
Host: connect.jobrad.org
Content-Type: application/json
Accept: application/json
Authorization: Bearer your_token_here
ETag: "686897696a7c876b7e"
Request-ID: 123e4567-e89b-12d3-a456-426614174000

In this example:

  • Pagination is controlled by page and perPage, corresponding to the second page and displaying 20 entries per page.
  • Sorting is specified by sortBy and order, here sorted by price in ascending order (asc).

The header parameters include:

  • Content-Type: application/json - Specifies the format of the sent data.
  • Accept: application/json - Specifies the desired format of the response data.
  • Authorization: Bearer your_token_here - Uses a bearer token for authentication.
  • Request-ID: 123e4567-e89b-12d3-a456-426614174000 - A unique ID for tracking this specific request.

Request Body​

The request body of an API request is essential for sending data, especially in POST, PUT, and PATCH methods, where new resources are created or existing ones are updated. A well-structured and consistently defined request body helps consumers of our APIs with data requests and manipulation.

Definition and Usage​

The request body must (MUST) be sent in JSON format unless there are compelling reasons to use a different format. This ensures that the data can be easily processed and interpreted.

Every request body must (MUST) follow a clear and precise schema definition, which should be available in the API documentation. This helps developers understand the expected structure and required fields.

Specification of Fields​

  • Required fields must (MUST) be clearly defined and documented. A field marked as required must be included in every corresponding API request to ensure successful operations.

    Example:

    For a POST request to create a bike lease, the request body might include the following required fields:
    {
      "model": "Trek Emonda",
      "leaseDuration": 12,
      "customerID": "123456"
    }

  • Optional fields should (SHOULD) also be clearly defined, and their exclusion must not result in an error. These fields allow users to provide additional, non-essential information.

    Example:

    An optional field for additional bike accessories in a POST request could be:
    {
      "accessories": ["Helmet", "Basket"]
    }

Validation and Format​

Data validation for incoming data in the request body must (MUST) be implemented to ensure the integrity of the API. This includes checking data types, required fields, and the format of specific information.

Error messages for validation failures should (SHOULD) be clear and helpful, so API users can understand how to resolve the issues. More details are provided in the "Error Handling and Communication" section.

Example of an API Request to Create a Bike Lease Contract:

HTTP Request:

POST /leases HTTP/1.1
Host: connect.jobrad.org
Content-Type: application/json
{
  "model": "Trek Emonda",
  "leaseDuration": 12,
  "customerID": "123456",
  "options": {
    "accessories": ["Helmet", "Basket"]
  }
}

This example shows how a well-structured and clearly defined request body simplifies API usage and avoids misunderstandings. The clear separation of required and optional fields helps both API developers and users to provide and transmit the necessary data correctly. Using an optional (SHOULD) parent "options" object for optional fields allows for flexibility and extensibility of the data model without disrupting the fundamental structure of the request body.