gh-secondsky-sap-skills-skills-sap-api-style/templates/rest-api-method-template.md

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".]

Parameter Name	Requirement	Data Type	Description	Location
[Name]	Required/Optional	[Type]	[Detailed description with constraints, pattern, valid values]	Path

Example:

Parameter Name	Requirement	Data Type	Description	Location
employeeId	Required	String	Unique employee identifier. Format: E followed by 5 digits. Pattern: E[0-9]{5}. Example: "E12345"	Path

Query Parameters

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

Parameter Name	Requirement	Data Type	Description	Location
[Name]	Required/Optional	[Type]	[Description with constraints, valid values, defaults]	Query

Example:

Parameter Name	Requirement	Data Type	Description	Location
limit	Optional	Integer	Maximum results per page. Range: 1-100. Default: 20. Example: "50"	Query
offset	Optional	Integer	Number of results to skip for pagination. Default: 0. Used with limit for pagination.	Query
department	Optional	String	Filter by department code. Valid: "SALES", "ENGINEERING", "FINANCE", "HR", "OPERATIONS". Example: "SALES"	Query
status	Optional	String	Filter by employee status. Valid: "ACTIVE", "INACTIVE", "LEAVE", "TERMINATED". Default: all statuses.	Query
sortBy	Optional	String	Sort field. Valid: "name", "hireDate", "department", "salary". Default: "name". Use - prefix for descending (e.g., "-hireDate")	Query

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:

Field Name	Requirement	Data Type	Description
[Name]	Required/Optional	[Type]	[Description with constraints, format, valid values, length, min/max]

Example:

Field Name	Requirement	Data Type	Description
firstName	Required	String	Employee's first name. Length: 1-50 characters. Alphanumeric and spaces only.
lastName	Required	String	Employee's last name. Length: 1-50 characters. Alphanumeric and spaces only.
email	Required	String	Corporate email address. Must be unique across system. Must be valid email format (RFC 5322).
department	Required	String	Department code. Valid: "SALES", "ENGINEERING", "FINANCE", "HR", "OPERATIONS". Example: "ENGINEERING"
hireDate	Optional	Date (YYYY-MM-DD)	Hire date of employee. Format: ISO 8601 date. Cannot be future date. Example: "2024-01-15"
salary	Optional	Decimal	Annual salary in USD. Minimum: 20000. Maximum: 10000000. Two decimal places. Example: 95000.00

---

Response

Status Codes

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

Status Code	Description
[Code]	[What this status means in context of this specific operation]

Example for GET method:

Status Code	Description
200 OK	Request successful. Response body contains employee data matching query.
400 Bad Request	Invalid query parameters or malformed request. Check parameter values and format.
401 Unauthorized	Authentication token missing, invalid, or expired. Obtain new token via authentication service.
403 Forbidden	Authenticated but insufficient permissions. User lacks ROLE_HR_USER required for read access.
404 Not Found	No employee found with specified ID (for single-resource GET).
429 Too Many Requests	Rate limit exceeded. Wait for X-RateLimit-Reset time before retrying.
500 Internal Server Error	Server encountered unexpected error. Contact support if issue persists.

Example for POST method:

Status Code	Description
201 Created	Employee successfully created. Location header contains URL to new employee. Response includes created employee data.
400 Bad Request	Validation failed. Check email uniqueness, required fields, field formats, and value constraints.
401 Unauthorized	Authentication token missing, invalid, or expired.
403 Forbidden	Insufficient permissions. Requires ROLE_HR_MANAGER or higher.
409 Conflict	Employee with this email already exists. Email must be unique.
500 Internal Server Error	Server error. Contact support.

Response Headers

Header Name	Description	Example Value
[Header name]	[What this header contains]	[Example value]

Example:

Header Name	Description	Example Value
Content-Type	Media type of response body	application/json
X-Total-Count	Total available records (for paginated responses)	5000
X-RateLimit-Remaining	API calls remaining in rate limit window	998
Location	URL of created/modified resource (201, 200 responses)	[https://api.example.com/v1/employees/E12346](https://api.example.com/v1/employees/E12346`)
ETag	Entity tag for caching and optimistic locking	"abc123def456"

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](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