/sap-api-style

REST API Method Template

How to Use This Template

Purpose: Document individual REST API methods/endpoints with complete request and response details.

When to Use:

• Creating documentation for a specific REST method (GET, POST, PUT, PATCH, DELETE)
• Detailed endpoint documentation linked from Overview template
• Providing exact parameter requirements and response examples

Instructions:

1. Replace all [bracketed text] with your actual content
2. Include complete, working HTTP request examples
3. Show real response examples with actual status codes
4. Document all possible status codes for this specific method
5. Test the endpoint and verify all examples work
6. Remove optional sections if not applicable

Cross-Reference: Use with REST API Overview Template for shared information.

Template Structure:

• Title & Introduction
• Usage section
• Request Details (method, permission, headers, parameters)
• Request Example(s)
• Response Details (status codes, body examples)
• Response Examples (success and error cases)

[Action Verb] [Resource Name]

[Provide a clear, concise description of what this method does. Include:

• Primary action performed
• What is retrieved, created, modified, or deleted
• Primary use case
• Key limitations or behaviors]

Example: "Retrieves a complete list of all employees in the system with support for filtering, sorting, and pagination. Returns employee summary data by default."

Usage

[Explain when and why to use this method, including:

• Specific scenarios where this method is appropriate
• When to use alternative methods instead
• Important prerequisites or constraints
• Any special behaviors or side effects]

Use this method when [explain primary scenario].

Key points:

• [Important characteristic, constraint, or behavior]
• [Related method or alternative, if applicable]
• [Performance consideration, size limit, or special note]
• [Business logic or workflow impact, if relevant]

Example: "Use this method to retrieve all employee records with optional filtering and pagination.

Key points:

• Supports filtering by multiple fields using query parameters
• Returns paginated results (default: 20 per page, max: 100 per page)
• Results sorted by employee ID unless otherwise specified via sortBy (e.g., sortBy=employeeId or sortBy=-employeeId for desc)
• Related method: GET /employees/{employeeId} for retrieving specific employee data
• Performance: Large result sets should use pagination to avoid timeout"

Request

Request Line

[HTTP METHOD] [Relative URI Path]

Example:

GET /employees
GET /employees/{employeeId}
POST /employees
PUT /employees/{employeeId}
PATCH /employees/{employeeId}
DELETE /employees/{employeeId}

HTTP Method

Method: [GET/POST/PUT/PATCH/DELETE]

[Brief explanation of what this HTTP method does in this context]

Method Details:

• GET: Retrieves resource(s) without modifying server state
• POST: Creates new resource with provided data
• PUT: Replaces entire resource with new data
• PATCH: Partially updates resource (merge semantics)
• DELETE: Deletes or deactivates resource

Permission Requirement

Permission: [Required role/permission for this method]

[Explanation of what this permission allows or why it's required]

Example: "Permission: ROLE_HR_MANAGER (read access)

Users with ROLE_HR_MANAGER or higher can call this method. Lower roles like ROLE_HR_USER cannot access this endpoint."

Common Request Headers

Refer to Common Request Headers in the API Overview.

[List any method-specific headers not covered in Overview]

Additional headers for this method (if applicable):

• [Header name]: [Description specific to this method]

Example: "Refer to Common Request Headers in overview.

Additional method-specific headers:

• X-Employee-View: Optional header to specify detail level ('summary', 'full', default: 'summary')"

Path Parameters

[If method has path parameters, include table. Otherwise, state "None".]

Example:

Query Parameters

[If method accepts query parameters, include table. Otherwise, state "None".]

Example:

Request Body

[For POST/PUT/PATCH methods, document request body structure. For GET/DELETE, state "None".]

For POST/PUT/PATCH:

{
  "[property]": "[value or type]",
  "[property]": "[value or type]"
}

Example:

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@company.com",
  "department": "ENGINEERING",
  "hireDate": "2024-01-15",
  "salary": 95000.00
}

Field Descriptions:

Example:

Response

Status Codes

[Document all HTTP status codes that can be returned by this specific method.]

Example for GET method:

Example for POST method:

Response Headers

Example:

Response Body

[Document the successful response body structure.]

For successful request:

{
  "[property]": "[value]",
  "[property]": "[value]"
}

Example:

{
  "employeeId": "E12345",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@company.com",
  "department": "ENGINEERING",
  "jobTitle": "Senior Software Engineer",
  "hireDate": "2020-06-01",
  "salary": 120000.00,
  "status": "ACTIVE",
  "createdAt": "2020-06-01T09:00:00Z",
  "lastModified": "2024-01-15T14:30:00Z"
}

Examples

Complete Request Example

[Provide full HTTP request with all headers and body.]

[HTTP METHOD] [Path]?[Query Parameters] HTTP/1.1
Host: [Host from Base URI]
Authorization: Bearer [token]
Content-Type: application/json
[Additional Headers]

[Request Body (if applicable)]

Example for GET:

GET /employees?limit=20&offset=0&status=ACTIVE HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/json

Example for POST:

POST /employees HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@company.com",
  "department": "ENGINEERING",
  "hireDate": "2024-01-15",
  "salary": 95000.00
}

Example for PATCH:

PATCH /employees/E12345 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
If-Match: "abc123def456"

{
  "department": "SALES",
  "salary": 105000.00
}

Complete Response Example (Success)

HTTP/1.1 [Status Code] [Status Message]
Content-Type: application/json
[Response Headers]

[Response Body]

Example for 200 OK:

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Remaining: 998
ETag: "abc123def456"

{
  "employeeId": "E12345",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@company.com",
  "department": "ENGINEERING",
  "jobTitle": "Senior Software Engineer",
  "hireDate": "2020-06-01",
  "salary": 120000.00,
  "status": "ACTIVE",
  "createdAt": "2020-06-01T09:00:00Z",
  "lastModified": "2024-01-15T14:30:00Z"
}

Example for 201 Created:

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://api.example.com/v1/employees/E12346

{
  "employeeId": "E12346",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@company.com",
  "department": "ENGINEERING",
  "hireDate": "2024-01-15",
  "status": "ACTIVE",
  "salary": 95000.00,
  "createdAt": "2024-01-15T10:30:00Z"
}

Error Response Examples

Example for 400 Bad Request:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "issue": "Email already exists",
        "value": "john.doe@company.com"
      },
      {
        "field": "salary",
        "issue": "Minimum salary is 20000",
        "value": "15000"
      }
    ]
  }
}

Example for 404 Not Found:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Employee not found",
    "details": {
      "resourceType": "Employee",
      "providedId": "E99999"
    }
  }
}

Example for 409 Conflict:

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "code": "DUPLICATE_EMPLOYEE",
    "message": "Employee with email already exists",
    "details": {
      "email": "john.doe@company.com",
      "existingEmployeeId": "E10001"
    }
  }
}

Related Methods

• Parent Overview
• Related Method 1
• Related Method 2

Template Version: 1.0 Last Updated: 2025-11-21 Compliance: SAP API Style Guide Section 50