[ADP-763] OpenAPI: Implicit Resource Indication

Guidance

• MUST document implicit resource indications in API descriptions
• SHOULD use clear and concise language to explain resource scoping
• MUST include authentication and authorization requirements when relevant to resource scoping
• SHOULD provide examples of how the implicit resource indication affects API responses

Overview

In API design, implicit resource indication refers to endpoints that return or manipulate a subset of resources based on the authenticated user's context or other non-explicit parameters.

Example

Here's an improved example of how to document an endpoint with implicit resource indication:

openapi: 3.1.0
info:
  title: Employee API
  version: 1.0.0
paths:
  /employees:
    get:
      summary: Get employees of the authenticated user's company
      description: >
        Retrieves a list of employees that belong to the company associated with the authenticated user.
        This endpoint implicitly scopes the results to the user's company and does not return employees from other companies.
        The user must have the 'read:employees' permission to access this endpoint.
      tags:
        - Employees
      security:
        - bearerAuth: []
      parameters:
        - name: department
          in: query
          description: Filter employees by department within the user's company
          schema:
            type: string
      responses:
        '200':
          description: A list of employees from the user's company
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Employee'
              example:
                - id: "12345"
                  name: "John Doe"
                  department: "Engineering"
                  companyId: "67890"
                - id: "67890"
                  name: "Jane Smith"
                  department: "Marketing"
                  companyId: "67890"
        '401':
          description: Unauthorized - User is not authenticated
        '403':
          description: Forbidden - User does not have the required permissions
        '404':
          description: Not Found - No employees found or user's company does not exist
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    Employee:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        department:
          type: string
        companyId:
          type: string

Design Approach

If the API's return results are affected by the current user's authentication or permissions, but this is not clearly stated in the document, it may lead to the user mistakenly thinking that they have the ability beyond their own permissions.

Related ADPs

• ADP-301: Resource-Oriented Design
• ADP-47: API Authentication and Authorization
• ADP-751: New OpenAPI Document
• ADP-756: OpenAPI Provide Examples

References

1. OpenAPI Specification
2. REST API Design Best Practices
3. API Security Best Practices