Skip to content
Skills Library
Programming · Review & audit

http-api-guidelines

/http-api-guidelines

This skill encodes the organizational guidelines for designing, developing, and versioning HTTP APIs. Use it when reviewing, designing, or building HTTP APIs to ensure compliance with the agreed-upon standards.

Repository
skills ↗
Licence
MIT
Last repository change
06.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
12
Deprecation

No signals detected. Repository changed on 06.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

This skill encodes the organizational guidelines for designing, developing, and versioning HTTP APIs. Use it when reviewing, designing, or building HTTP APIs to ensure compliance with the agreed-upon standards.

Original author description

This skill encodes the organizational guidelines for designing, developing, and versioning HTTP APIs. Use it when reviewing, designing, or building HTTP APIs to ensure compliance with the agreed-upon standards.

How it works

  1. When to use
  2. API Levels
  3. General Rules
  4. Documentation
  5. HTTP Verbs
  6. URLs and Routes
  7. Idempotency
  8. HTTP Status Codes
  9. Asynchronous Operations
  10. Versioning
Original SKILL.md headings · 289 lines, 1,990 words
SKILL.md preview
---
name: http-api-guidelines
description: "This skill encodes the organizational guidelines for designing, developing, and versioning HTTP APIs. Use it when reviewing, designing, or building HTTP APIs to ensure compliance with the agreed-upon standards."
---

## When to use
Use this skill when:
- Designing a new HTTP API
- Reviewing an existing API for compliance
- Answering questions about API design conventions
- Creating or reviewing pull requests that involve HTTP API changes
- Generating OpenAPI specifications

---

## API Levels

APIs are classified into three levels. All APIs **must** be considered private unless explicitly stated otherwise.

### Private APIs
- Scoped to a single product / repository / team.
- Versioning and backwards compatibility are less critical.
- Can often be changed in a single pull request covering both server and client.
- Communication about changes is informal ("just tap someone on the shoulder").

### Internal APIs
- Represent contracts between different components / services / products within the organization.
- Require documentation (though less exhaustive than public).
- Versioning and backwards compatibility **are** important — typically two versions must be maintained simultaneously.
- Changes are communicated via meetings, chat or work items.

### Public APIs
- Consumed by external parties whose code is not maintained by the organization.
- Must be designed and developed with great care.
- Support cycles span multiple years; breaking changes are very costly to coordinate.
- Require detailed developer documentation via OpenAPI, with reference examples where needed.
- Changes must be broadly communicated via release notes, `obsolete` markers, and version headers.

---

## General Rules

### Language
- All code and documentation visible to API consumers **must** be written in **American English** (e.g., `Canceled` not `Cancelled`).

### Casing
- API routes **must** use **lowercase only**.
- Compound words in URLs **must** use **kebab-casing** (e.g., `collective-schemes` not `collectiveSchemes`).

### Naming
- **Never** use product or company names in HTTP APIs. Use functional names instead to avoid large-scale impact if a product is replaced or rebranded.

### Format
- **Never** support multiple formats (e.g., JSON and XML) for private and internal APIs — it only adds complexity.
- Public APIs **must** support at least **JSON**; additional formats (XML, gRPC, etc.) are optional.
- Public APIs **must** use the `Content-Type` and `Accept` headers for content negotiation.
- **Never** use the `Accept-Charset` header. Always use **UTF-8**.

### Compression
- **Never** use HTTP compression for public APIs over SSL/TLS unless CSRF protections are in place (see [BREACH](https://en.wikipedia.org/wiki/BREACH) and [CRIME](https://en.wikipedia.org/wiki/CRIME)). Note: this no longer applies to TLS 1.3.
- Compression **is** allowed and recommended for CDN servers serving static content.

### Performance
- API requests **must** meet the following response-time targets:

| Percentile | Maximum Response Time |
|---|---|
| p50 | 50–100 ms |
| p90 | 200–300 ms |
| p95 | 300–500 ms |
| p99 | < 1 second |

- If targets are not achievable, consider HTTP caching, server-side caching, enforced paging with a max page length, or making the operation asynchronous.

### Statefulness
- APIs **must** be stateless. **Never** rely on sticky sessions.

---

## Documentation

- **Must** use the **OpenAPI** standard to document APIs.
- **Must** make the API level (private / internal / public) explicit (e.g., via a Tag in Azure Functions).
- Consider keeping an overview of the relevant APIs in one central place, such as a wiki or a developer portal.
- The API documentation UI **must** be hosted at **`/api-docs`** (for all levels).
- OpenAPI specification files **must** be hosted at level-specific routes:
  - Private: `/api-docs/[feature]/v[version]/open-api-private.json`
  - Internal: `/api-docs/[feature]/v[version]/open-api-internal.json`
  - Public: `/api-docs/[feature]/v[version]/open-api.json`

---

## HTTP Verbs

Use HTTP methods according to their defined semantics:

| Method | Semantics |
|---|---|
| `GET` | Retrieve a representation of the resource. |
| `POST` | Create a new resource (or trigger an operation that doesn't create a resource, e.g., when query parameters would make the query string too long). |
| `PUT` | Create or **fully replace** the resource. The client sends the complete resource. |
| `PATCH` | **Partially update** a resource. Only the fields to change are sent. |
| `DELETE` | Remove the resource. |

### Example resource matrix

| Resource | POST | GET | PUT / PATCH | DELETE |
|---|---|---|---|---|
| `/clients` | Create a new client | Retrieve all clients | Bulk update all clients | Remove all clients |
| `/clients/123` | — | Retrieve client 123 | Update client 123 | Remove client 123 |
| `/clients/123/contracts` | Create a contract for client 123 | Retrieve all contracts for client 123 | Bulk update contracts for client 123 | Remove all contracts for client 123 |

---

## URLs and Routes

### Templates
```
https://[domain]:[port]/resource-name[/resource-id][/sub-resource-name][/sub-resource-id]
https://[domain]:[port]/[resource-name][/resource-id][/fields-group-name]
```

### Rules
- Use **plural nouns** for resources (e.g., `/api/connections/1` not `/api/connection/1`).
- Use **nouns**, not verbs, to describe resources — the HTTP verb conveys the operation.
- **Never** nest relationships deeper than **three levels** (e.g., stop at `clients/1/contracts/2/eans/…`). Exceptions are allowed for reporting APIs (e.g., OData), but watch performance.
- Treat `/people` and `/people/` identically — both must return the same result.
- URLs **must** be human-readable and discoverable.
- Use **stable identifiers** (GUIDs, numeric IDs) that do not change over time, but no technical identifiers such as database primary keys
- Consider adding a user-friendly alias URL alongside the durable URL (e.g., `/people/my/inbox` → `/people/7011042402/inbox`).
- **Never** expose database identifiers as durable API identifiers — this couples the API to the storage technology.

---

## Idempotency

- All `GET`, `PUT`, and `DELETE` requests **must** be idempotent.
- Consider making `POST` and `PATCH` requests idempotent for critical data (e.g., payment APIs). Techniques include unique entity fields to detect duplicate POSTs, or a client-supplied idempotency key stored server-side.

---

## HTTP Status Codes

### General
| Code | When to Use |
|---|---|
| `400 Bad Request` | The request is technically unprocessable (e.g., plain text sent when JSON expected). |
| `401 Unauthorized` | The user/application must authenticate. |
| `403 Forbidden` | Authenticated but insufficient permissions. |
| `409 Conflict` | Technically valid request that cannot be processed due to system state (e.g., unique key violation, last-admin deletion, workflow violation). |
| `422 Unprocessable Entity` | The request payload is invalid (e.g., missing required field, field too long). Do **not** use for state conflicts — use `409` instead. |
| `429 Too Many Requests` | Rate limit exceeded. |

- **Must** use the **Problem Details** standard ([RFC 9457](https://learn.microsoft.com/en-us/aspnet/core/web-api/handle-errors?view=aspnetcore-8.0#client-error-response)) to communicate errors to clients.

### GET
| Code | When to Use |
|---|---|
| `200 OK` | The request returned results. |
| `404 Not Found` | Resource not found. Consider a debug log entry to distinguish "route not registered" from "resource does not exist". |

### POST
| Code | When to Use |
|---|---|
| `201 Created` | Resource created synchronously. Include a `Location` header pointing to the GET endpoint for the new resource. |
| `202 Accepted` | Resource accepted for asynchronous creation. Include a `Location` header pointing to the future GET endpoint or a status-polling endpoint. |

### PUT / PATCH
| Code | When to Use |
|---|---|
| `200 OK` | Update processed; response body contains the result. |
| `204 No Content` | Update processed; no response body. Prefer this for PUT (full replace) to save bandwidth. |
| `202 Accepted` | Update accepted for asynchronous processing. |

### DELETE
| Code | When to Use |
|---|---|
| `200 OK` | Deletion processed; response body contains content. |
| `204 No Content` | Deletion processed; no response body. Prefer `200 OK` in general. |
| `404 Not Found` | Resource doesn't exist. If the resource was possibly deleted, return `200 OK` instead. |

### API Gateways / Reverse Proxies
| Code | When to Use |
|---|---|
| `502 Bad Gateway` | Invalid response received from an upstream server. |
| `504 Gateway Timeout` | No timely response received from an upstream server. |

---

## Asynchronous Operations

When a `POST`, `PUT`, `PATCH`, or `DELETE` would cause unacceptable latency as a blocking call, make it asynchronous.

- Return `202 Accepted`.
- If the delay is negligible (milliseconds), documenting the eventual consistency on the API itself is sufficient.
- If the delay is significant (seconds+), provide a **status-polling endpoint** and include its URI in the `Location` header of the `202` response.

### Long-running async flow

```
POST /api/resource
→ 202 Accepted
  Location: /api/resource/status/12345

GET /api/resource/status/12345   (poll until complete)
→ 200 OK
  { "status": "InProgress" | "Completed" }

(when the operation creates a new resource, the final poll returns:)
→ 201 Created
  Location: /api/resource/12345
```

---

## Versioning

### General
- Allow the caller to select the version via **both** a query-string parameter and an HTTP header. The query-string value takes precedence.
- Use **`api-version`** as the parameter/header name.
- When no version is specified: default to the **latest** version for public APIs; for internal APIs the default may be the **oldest supported** version.
- Announce supported versions via the **`api-supported-versions`** response header (comma-separated).
- Announce deprecated versions via the **`api-deprecated-versions`** response header (comma-separated).
- Use **Semantic Versioning** limited to the format `<MAJOR>-<PRE-RELEASE-TAG>`:
  - Increment MAJOR for incompatible changes.
  - Use a pre-release tag (`alpha` or `beta`) for unstable versions.

### Per level

| Level | Versioning Required? | Max Concurrent Versions | Notes |
|---|---|---|---|
| Private | Generally no | 1 (avoid multiple) | Exception: BFF called from a frontend in a mono-repo may need 2 versions. Consider versioning when the client is not deployed simultaneously (e.g., desktop apps). |
| Internal | Yes | 2–3 | Document and communicate deprecated versions. |
| Public | Always | ≥ 3 | Avoid supporting too many versions to keep maintenance costs down. |

### Breaking changes
A breaking change **must** result in a MAJOR version bump, unless all dependent parties can be updated simultaneously. Examples of breaking changes:
- Removing or renaming APIs or parameters
- Changing behavior of an existing API
- Changing error codes, error contracts, or response codes

---

## Pagination

- Public APIs **must** always support pagination.
- Use the `$` prefix for global query-string parameters (e.g., `$skip`, `$take`) to avoid conflicts with local parameters.
- Use `$skip` and `$take` to select the page and limit the number of records.
  - Example: `https://api.contoso.com/contracts?$skip=1000&$take=500`
- `$take` **must** have a hard maximum value — never allow unbounded requests.

---

## Security

- **Never** use HTTP — always HTTPS.
- Perform regular checks against the [OWASP API Security Top 10](https://owasp.org/www-project-api-security/).
- Secure all APIs with **OAuth 2.0**. Any unauthenticated endpoint must be validated with the security team and documented.
- Use the **Client Credentials** flow for service-to-service authentication.
- Use **Cookie authentication** for APIs called from the website.
- Consider supporting **CORS** configuration.
- **Never** return stack traces to the client. Return a correlation ID instead and log the error with that ID.

---

## Caching

- **Must** always specify an explicit cache expiration using `Cache-Control: max-age=…` or the `Expires` header. Even without caching, use `Cache-Control: no-cache`.
- **Must** always specify caching scope using `public` or `private`. Use `Cache-Control: private` to prevent intermediate proxies from caching sensitive content.
- Use `no-store` to prevent browsers from storing data at all (`no-cache` still allows local storage; it only forces revalidation).
- Consider using **ETag** or **`Last-Modified`** headers to enable conditional requests and extend effective cache duration.

---

## JSON Conventions

- Represent dates and times in **ISO 8601** format (e.g., `2022-10-31` or `2022-10-31T09:00:00-05:00` with time-zone offset).
- Use **UTC** when the value is not a local time (e.g., `2022-10-31T09:00:00Z`).
- Use **camelCase** for JSON property names (e.g., `clientId`, `contractType`).
- Use **functional names** for properties — never expose raw database column names.
- Use **plural names** for arrays and collections (e.g., `contracts`, `connections`).
- **Never** represent an empty array as `null`.
- Use `null` to indicate a property has no value. If a property is not applicable, omit it from the JSON body entirely.

---

## References
- [HTTP Caching for Static Assets](https://imagekit.io/blog/ultimate-guide-to-http-caching-for-static-assets/)
- [BREACH attack](https://en.wikipedia.org/wiki/BREACH)
- [CRIME attack](https://en.wikipedia.org/wiki/CRIME)
- [ASP.NET Core Problem Details](https://learn.microsoft.com/en-us/aspnet/core/web-api/handle-errors?view=aspnetcore-8.0#client-error-response)
- [OWASP API Security Top 10](https://owasp.org/www-project-api-security/)

Versions

The database has no other skills named http-api-guidelines.

Database snapshot: 13.11.2026 · package version 38750e11c91b (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100api-standards
    Apply agnostic HTTP/API design standards (REST shape, versioning, errors, naming) without company contracts. Use when designing or reviewing APIs or invoking /api-standards.
  • 100api-design
    Guidelines for designing RESTful APIs and TypeScript interfaces. Use when designing new endpoints, reviewing API contracts, or structuring data models.
  • 100api-design
    REST API design patterns for resource naming, HTTP methods, status codes, pagination strategy, error envelopes, versioning, and rate limiting. Use when designing, reviewing, or refactoring HTTP APIs and endpoint contracts.
  • 100api-design-patterns
    RESTful API design, error handling, versioning, and best practices. Use when designing APIs, reviewing endpoints, implementing error responses, or setting up API structure. Triggers on "design API", "review API", "REST best practices", or "API patterns".
  • 100golang-api-server
    Build HTTP services, REST APIs, and middleware in Go. Use when building Go HTTP servers, REST APIs, or custom middleware.
  • 100rest-api
    REST API design principles. Covers resources, methods, and status codes. Use when designing or reviewing REST APIs. USE WHEN: user mentions "REST API", "RESTful", "HTTP methods", "status codes", "resource naming", "API endpoints", "pagination", "versioning", asks about "how to…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.