ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-367] HTTP Profile ​

Overview ​

RFC 6906 introduces the "profile" link relation type, which allows API designers to convey additional semantics beyond those described by the media type alone.

Guidance ​

  • APIs with audience≥PARTNER_EXTERNAL SHOULD use the "profile" link relation to indicate that a resource representation conforms to one or more profiles.

  • Profiles SHOULD be clearly defined and documented. Documentation SHOULD include:

    • A unique identifier (URI) for the profile.
    • A description of the additional semantics, constraints, and conventions imposed by the profile.

  • When applicable, the "profile" link relation SHOULD be included in HTTP headers to convey profile information. For example:

    http
    Link: <http://example.com/profiles/resource-profile>; rel="profile"

  • The profile link SHOULD be an absolute URI rather than a relative one. The URI MUST reside within the same URL namespace as the API endpoints. For instance, if all API endpoints are located at https://api.test.com/v1/, the profile URIs should also be located within the same context path (e.g., https://api.test.com/v1/payment/profiles/payment-method+v1).

  • If supporting REST maturity level 3, the "profile" link relation SHOULD be embedded within hypermedia formats (e.g., JSON, HAL) to indicate that a specific resource conforms to a profile. For example:

    json
    {
  "name": "Sample Resource",
  "description": "This is a sample resource.",
  "_links": {
    "profile": {
      "href": "http://example.com/profiles/sample-resource"
    }
  }
}

  • Profiles SHOULD be versioned to accommodate changes and improvements over time. The profile URI SHOULD include version information when applicable. For example:

    http
    Link: <http://example.com/profiles/resource-profile/v1.0>; rel="profile"

  • Profiles SHOULD be designed to promote interoperability between different systems. They SHOULD specify validation rules to ensure that resource representations conform to the profile.

  • When updating profiles, care SHOULD be taken to maintain backward compatibility. Deprecated elements SHOULD be clearly documented, and clients SHOULD be given ample time to transition to new versions.

  • API designers SHOULD consider using OpenAPI schema as a basis for profiles.

  • Profiles MAY be used in conjunction with content negotiation to allow clients to request specific representations of resources.

  • API documentation SHOULD clearly explain how to interpret and use profiles, including any implications for client behavior.

  • DRAFT SHOULD consider creating a profile registry for your organization to manage and document all available profiles.

Examples ​

Profile Declaration in OpenAPI ​

yaml
openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /resources:
    get:
      responses:
        '200':
          description: Successful response
          headers:
            Link:
              schema:
                type: string
              example: '<http://example.com/profiles/resource/v1>; rel="profile"'

Reference ​

Design reference ​