Best Practices on Resource Definitions - wso2/carbon-apimgt GitHub Wiki

1. Resource Path Naming Conventions

  • Use nouns instead of verbs in resource paths.
    Example : /users, /orders instead of /getUser, /createOrder

  • Use lowercase letters in resource names.
    Example : /client-certificates instead of /ClientCertificates

  • Use hyphens (-) to separate words in compound resource names.
    Example : /change-requests instead of /change_requests, /changerequests

2. HTTP Method Usage

Use the appropriate HTTP method based on the nature of the operation:

Method Purpose
GET Retrieve resources
POST Create new resources
PUT Update existing resources
DELETE Remove resources
PATCH Partially update resources

3. Define Requests and Responses

  • Define structured and descriptive request/response bodies.
  • Reuse definitions using $ref to promote consistency and avoid duplication.

Example:

responses:
  200:
    description: |
      OK. Change request list is returned.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ChangeRequestList'
  404:
    $ref: '#/components/responses/NotFound'
  500:
    $ref: '#/components/responses/InternalServerError'

4. Error Handling

Use appropriate status codes:

  • 2xx: Successful responses
  • 4xx: Client errors (e.g., 400 Bad Request, 401 Unauthorized, 404 Not Found)
  • 5xx: Server errors (e.g., 500 Internal Server Error, 503 Service Unavailable)

5. Reusability and Schema Composition

Use JSON Schema composition keywords to simplify definitions:

  • oneOf: Exactly one schema must match
  • anyOf: At least one schema must match
  • allOf: Combines multiple schemas
  • not: Negate a schema

Example:

allOf:
  - $ref: '#/components/schemas/BaseResource'
  - type: object
    properties:
      additionalField:
        type: string

4. Error Handling

Use appropriate status codes:

  • 2xx: Successful responses
  • 4xx: Client errors (e.g., 400 Bad Request, 401 Unauthorized, 404 Not Found)
  • 5xx: Server errors (e.g., 500 Internal Server Error, 503 Service Unavailable)

5. Reusability and Schema Composition

Use JSON Schema composition keywords to simplify definitions:

  • oneOf: Exactly one schema must match
  • anyOf: At least one schema must match
  • allOf: Combines multiple schemas
  • not: Negate a schema

Example:

allOf:
  - $ref: '#/components/schemas/BaseResource'
  - type: object
    properties:
      additionalField:
        type: string

6. Security and Scopes

Define security requirements at the resource level to enforce authorization. Use relevant OAuth2 scopes to control access based on user roles or permissions.

Example:

security:
  - OAuth2Security:
      - apim:api_view
      - apim:api_manage
      - apim:client_certificates_view
      - apim:client_certificates_manage

7. Tagging

Use tags to group and categorize related resources in the API documentation