Best Practices on Resource Definitions

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