Przejdź do treści
Biblioteka skilli
Programowanie · Planowanie

rest-api

/rest-api

Wspiera projektowanie architektury REST API: semantykę HTTP, specyfikacje OpenAPI/Swagger, metody idempotentne, hipermedia (HATEOAS) i wzorce paginacji.

Repozytorium
Agent-Skills ↗
Licencja
MIT
Ostatnia zmiana repozytorium
01.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
3
Przestarzałość

Brak sygnałów. Repozytorium zmienione 01.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Wspiera projektowanie architektury REST API: semantykę HTTP, specyfikacje OpenAPI/Swagger, metody idempotentne, hipermedia (HATEOAS) i wzorce paginacji.

Oryginalny opis (EN)

Expert REST API architecture assistance covering HTTP semantics, OpenAPI/Swagger specifications, idempotent methods, hypermedia (HATEOAS), and pagination patterns. Use when designing web APIs, structuring resource endpoints, standardizing error formats, or implementing RESTful conventions.

Jak działa

  1. When to Use
  2. Quick Start
  3. Core Concepts
  4. Common Patterns
  5. Best Practices
  6. Troubleshooting
  7. References
Sekcje z nagłówków SKILL.md, w oryginale · 142 linii, 639 słów
Podgląd SKILL.md
---
name: rest-api
description: Expert REST API architecture assistance covering HTTP semantics, OpenAPI/Swagger specifications, idempotent methods, hypermedia (HATEOAS), and pagination patterns. Use when designing web APIs, structuring resource endpoints, standardizing error formats, or implementing RESTful conventions.
---

# REST API

Representational State Transfer (REST) is the architectural style for distributed hypermedia systems. It relies on stateless, client-server, cacheable communications protocols (mostly HTTP).

## When to Use

- **Universal Public Web APIs**: Building open, standardized APIs intended for third-party developers, webhooks, and partner integrations.
- **HTTP Caching & CDN Optimization**: Maximizing cacheability using standard HTTP response headers (`Cache-Control`, `ETag`, `Last-Modified`).
- **Resource-Oriented CRUD Operations**: Designing intuitive resource hierarchies with standard HTTP semantics (GET, POST, PUT, PATCH, DELETE).
- **Stateless Integration**: Delivering scalable stateless APIs consumed effortlessly by any HTTP client on any platform.

## Quick Start

```typescript
// Express.js Example
app.get("/users/:id", async (req, res) => {
  const user = await db.find(req.params.id);
  if (!user) return res.status(404).json({ error: "Not Found" });

  // HATEOAS (Hypermedia As The Engine Of Application State) - optional but "True REST"
  res.json({
    ...user,
    links: {
      self: `/users/${user.id}`,
      orders: `/users/${user.id}/orders`,
    },
  });
});
```

## Core Concepts

### HTTP Semantics & Idempotency

Different HTTP verbs carry formal idempotency and safety guarantees:

| Method   | Safe | Idempotent | Usage                                 |
| :------- | :--- | :--------- | :------------------------------------ |
| `GET`    | Yes  | Yes        | Retrieve resource representation      |
| `POST`   | No   | No         | Create new resource or trigger action |
| `PUT`    | No   | Yes        | Replace resource entirely             |
| `PATCH`  | No   | No / Yes   | Partially update resource             |
| `DELETE` | No   | Yes        | Remove resource                       |

### Standardized Error Representations (RFC 7807 / 9457)

Returns machine-readable `application/problem+json` error responses:

```json
{
  "type": "https://api.example.com/errors/invalid-payment",
  "title": "Invalid Payment Source",
  "status": 422,
  "detail": "The payment card provided has expired.",
  "instance": "/orders/415/payments"
}
```

### Content Negotiation & ETag Caching

Validates whether cached client data is still fresh without resending full payloads:

```typescript
app.get("/api/v1/users/:id", async (req, res) => {
  const user = await db.getUser(req.params.id);
  const etag = crypto
    .createHash("md5")
    .update(JSON.stringify(user))
    .digest("hex");

  if (req.headers["if-none-match"] === etag) {
    return res.status(304).end(); // Not Modified
  }

  res.setHeader("ETag", etag);
  res.setHeader(
    "Cache-Control",
    "public, max-age=60, stale-while-revalidate=300",
  );
  res.json(user);
});
```

## Common Patterns

### Cursor-Based Pagination

**Problem**: Offset-based pagination (`OFFSET 10000`) degrades database performance and skips items on concurrent writes.  
**Solution**: Use monotonic cursor identifiers (e.g. `created_at` + `id`).

```typescript
// GET /api/v1/posts?cursor=2026-09-27T10:00:00Z&limit=20
app.get("/api/v1/posts", async (req, res) => {
  const { cursor, limit = 20 } = req.query;
  const posts = await db
    .select()
    .from(postsTable)
    .where(
      cursor ? lt(postsTable.createdAt, new Date(cursor as string)) : undefined,
    )
    .orderBy(desc(postsTable.createdAt))
    .limit(Number(limit) + 1);

  const hasMore = posts.length > Number(limit);
  const data = hasMore ? posts.slice(0, -1) : posts;
  const nextCursor = hasMore
    ? data[data.length - 1].createdAt.toISOString()
    : null;

  res.json({ data, pagination: { hasMore, nextCursor } });
});
```

## Best Practices

**Do**:

- Use Nouns for Resource URIs: Use `/api/v1/orders` rather than action verbs like `/api/v1/getOrders` or `/api/v1/createOrder`.
- Implement Idempotency Keys on Mutating Requests: Require `Idempotency-Key` headers on POST/PATCH requests to prevent duplicate charges.
- Document with OpenAPI 3.1: Generate automated Swagger docs, SDK clients, and request validation schemas from OpenAPI specs.
- Implement Monotonic Cursor Pagination: Use `limit` and `starting_after` cursor pagination for high-volume datasets.

**Don't**:

- Return HTTP 200 with `{ "error": "..." }`: Always return correct HTTP status codes (`400`, `401`, `403`, `404`, `422`, `500`).
- Break API contracts without versioning: Prefix endpoints with `/v1/` or use header versioning when introducing breaking changes.
- Expose raw internal database column names: Map private column names to clean, camelCased JSON fields.

## Troubleshooting

| Error                        | Cause                                  | Solution                                             |
| :--------------------------- | :------------------------------------- | :--------------------------------------------------- |
| `405 Method Not Allowed`     | Sending POST to a GET-only endpoint.   | Check HTTP verb.                                     |
| `415 Unsupported Media Type` | Sending XML when JSON expected.        | Set `Content-Type: application/json`.                |
| `CORS Error`                 | Browser blocking cross-origin request. | Set `Access-Control-Allow-Origin` headers on server. |

## References

- [Restful API Design (Microsoft)](https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design)
- [Richardson Maturity Model](https://martinfowler.com/articles/richardsonMaturityModel.html)

Wersje

RepozytoriumWynikLicencja
Ta strona · G1Joshi/Agent-Skills100MIT
TerminalSkills/skills100Apache-2.0
envigoinnovations/subscriby-agentic-kit100MIT
claude-dev-suite/claude-dev-suite100MIT
vinnie357/claude-skills100MIT

Migawka bazy z 13.11.2026 · wersja paczki 7d2c37b0898a (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100restful-hateoas
    Prowadzi projektowanie RESTful API w Ruby on Rails według modelu dojrzałości Richardsona do poziomu 3 (HATEOAS): zasoby, semantyka HTTP, hipermedia, negocjacja treści i ewolucja API.
  • 100api-design-patterns
    Podaje wzorce REST API: wersjonowanie, odpowiedzi błędów, paginacja i konwencje OpenAPI, także przy konfiguracji dokumentacji Swagger.
  • 90api-contract-design
    Podpowiada wzorce projektowania API REST i GraphQL, specyfikacje OpenAPI/Swagger, strategie wersjonowania i uwierzytelniania.
  • 100rest
    Projektuje REST API: OpenAPI 3.1, semantykę HTTP, zasoby, stronicowanie, cache, negocjację treści, CORS, limity i obsługę błędów.
  • 100common-api-design
    Stosuje konwencje REST API: semantykę HTTP, kody statusu, wersjonowanie, paginację i standardy OpenAPI, niezależnie od frameworka.
  • 100common-api-design
    Stosuje konwencje projektowania REST API: metody HTTP, kody statusu, wersjonowanie, stronicowanie i specyfikację OpenAPI.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.