API Guidelines
  • adidas API Guidelines
  • General Guidelines
    • Introduction
    • API First
    • Contract
    • Immutability
    • Robustness
    • Common Data Types
    • Version Control System
    • Minimal API Surface
    • Rules for Extending
    • JSON
    • Security
    • Tooling
  • REST API Guidelines
    • Introduction
    • Core REST Principles
      • OpenAPI Specification
      • API Design Platform
      • Design Maturity
      • Testing
    • Protocol
      • HTTP
      • TLS
      • Separate Concerns
      • Request Methods
      • Status Codes
    • Message
      • Message Formats
      • Content Negotiation
      • HAL
      • Problem Detail
      • Foreign Key Relations
    • Application
      • Corporate Data Model
      • Common Data Types
    • Execution
      • Pagination
      • Long Running Tasks
        • Polling
        • Callback
        • Files Upload
      • Batch Operations
      • Search Requests
      • Query Requests with Large Inputs
      • Choosing Fields and Embedded Resources
      • Localization
      • Rate Limiting
      • Caching
      • Testing Enviroments
    • Evolution
      • Naming Conventions
      • Reserved Identifiers
      • URI Structure
      • Changes and Versioning
      • Phasing out Old Versions
    • Guides
      • API Testing CI Environment
      • Complete API Development
    • API Clients
      • Loose Coupling
    • Further References
  • Asynchronous API Guidelines
    • Introduction
    • Core Asynchronous Principles
      • Event Driven Architectures
      • Messages
        • Commands
        • Queries
        • Events
          • Events as Notifications
          • Events to Replicate Data
      • Protocols
      • Coupling
      • Bounded Context
      • Stream Processing
      • Naming Conventions
      • Tooling
        • Editors
        • Command Line Interface (CLI)
        • Generators
    • Kafka Asynchronous Guidelines
      • Introduction
        • Why AsyncAPI?
      • AsyncAPI Version
      • Internal vs Public Specifications
      • Key/Value Format
      • Message Headers
      • Specification Granularity
      • Self-Contained Specifications
        • Meaningful Descriptions
      • Schema Data Evolution
        • Backward Compatibility
        • Forward Compatibility
        • Full Compatibility
      • Automatic Schema Registration
      • Contact Information
      • AsyncAPI ID
      • Servers
      • Channels
      • Schemas
      • Security Schemes
      • External Docs
Powered by GitBook
On this page
  • Response Message Fields
  • Example
  • Embedded Resources
  • Example
  • Reasonable Defaults
  • Resource Variants
  1. REST API Guidelines
  2. Execution

Choosing Fields and Embedded Resources

Response Message Fields

Every request that may result in a response with a non-trivial body SHOULD implement the fields query parameter. If provided, the value of this parameter must be a comma-separated list of top-level response message fields.

Upon receiving such a request, in the event of a 2xx response, the service SHOULD respond with a message that includes only top-level fields specified in the fields parameter. That includes HAL-specific fields (_links and _embedded).

Example

Retrieve only some details of an Order resource:

HTTP Request

GET /order/1234?fields=_links,orderNumber,status HTTP/1.1
Accept: application/hal+json

HTTP Response

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
  "_links": {
    "self": { "href": "/orders/1234" },
    "author": { "href": "/users/john" },
    "items": [ ... ]
  },
  "orderNumber": 1234,
  "status": "pending"
}

Embedded Resources

Similarly to the fields query parameter, every request that might result in a response containing related embedded resource representations SHOULD implement the embedded query parameter. If, provided the value of the embedded query parameter MUST be a comma-separated list of relation identifiers.

Upon receiving such a request, in the event of a 2xx response, the service SHOULD respond with a message that "embeds" (see HAL _embedded field) only the related resources specified in the embedded parameter.

Example

Embed only information about the Author of an Order resource. We are not interested in Items that are in this order.

HTTP Request

GET /order/1234?embed=author HTTP/1.1
Accept: application/hal+json

HTTP Response

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
  "_links": {
    "self": { "href": "/orders/1234" },
    "author": { "href": "/users/john" },
    "items": [ ... ]
  },
  "orderNumber": 1234,
  "itemCount": 42,
  "status": "pending",
  "_embedded": {
    "author": {
      "_links": { "self": "/users/john" },
      "name": "John Appleseed",
      "email": "john@apple.com"
    }
  }
}

Reasonable Defaults

When fields and embedded parameters are not provided or not implemented the server SHOULD return reasonable default field and/or embedded resources. The defaults MUST always contain the _links field, where available.

Resource Variants

The facility of fields and embedded parameters doesn't impose any restriction of creating new resource variants.

It is OK to create a new resource just as a compound resource only to provide selected fields or blend-embed some existing resources together.

PreviousQuery Requests with Large InputsNextLocalization

Last updated 6 years ago