Labsco
langchain-ai logo

api-docs

★ 108

by langchain-ai · part of langchain-ai/skills-benchmarks

OpenAPI documentation and REST API design patterns

🔥🔥🔥✓ VerifiedFreeQuick setup
#git
🧩 One of 7 skills in the langchain-ai/skills-benchmarks package — works on its own, and pairs well with its siblings.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

API Documentation Standards

Design and document RESTful APIs following industry standards.

OpenAPI Specification

Always document APIs using OpenAPI 3.0+:

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0

paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email

REST Conventions

  1. Use nouns for resources: /users, /orders
  2. Use HTTP methods correctly: GET, POST, PUT, PATCH, DELETE
  3. Return appropriate status codes: 200, 201, 400, 404, 500
  4. Use pagination for lists: ?page=1&limit=20
  5. Version your API: /v1/users

Error Responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": [
      {"field": "email", "message": "Invalid email format"}
    ]
  }
}