API Design

When to use this skill

Designing new REST APIs

Creating GraphQL schemas

Refactoring API endpoints

Documenting API specifications

API versioning strategies

Defining data models and relationships

Instructions

Step 1: Define API requirements

Identify resources and entities

Define relationships between entities

Specify operations (CRUD, custom actions)

Plan authentication/authorization

Consider pagination, filtering, sorting

Step 2: Design REST API

Resource naming

:

Use nouns, not verbs:

/users

not

/getUsers

Use plural names:

/users/{id}

Nest resources logically:

/users/{id}/posts

Keep URLs short and intuitive

HTTP methods

:

GET

Retrieve resources (idempotent)

POST

Create new resources

PUT

Replace entire resource

PATCH

Partial update

DELETE

Remove resources (idempotent)

Response codes

:

200 OK

Success with response body

201 Created

Resource created successfully

204 No Content

Success with no response body

400 Bad Request

Invalid input

401 Unauthorized

Authentication required

403 Forbidden

No permission

404 Not Found

Resource doesn't exist

409 Conflict

Resource conflict

422 Unprocessable Entity

Validation failed

500 Internal Server Error

Server error

Example REST endpoint

:

GET /api/v1/users # List users

GET /api/v1/users/{id} # Get user

POST /api/v1/users # Create user

PUT /api/v1/users/{id} # Update user

PATCH /api/v1/users/{id} # Partial update

DELETE /api/v1/users/{id} # Delete user

Step 3: Request/Response format

Request example

:

POST /api/v1/users

Content-Type

:

application/json

{

"name"

:

"John Doe"

,

"email"

:

"john@example.com"

,

"role"

:

"admin"

}

Response example

:

HTTP/

1.1

201

Created

Content-Type

:

application/json

Location

:

/api/v1/users/

123

{

"id"

:

123

,

"name"

:

"John Doe"

,

"email"

:

"john@example.com"

,

"role"

:

"admin"

,

"created_at"

:

"2024-01-15T10:30:00Z"

,

"updated_at"

:

"2024-01-15T10:30:00Z"

}

Step 4: Error handling

Error response format

:

{

"error"

:

{

"code"

:

"VALIDATION_ERROR"

,

"message"

:

"Invalid input provided"

,

"details"

:

[

{

"field"

:

"email"

,

"message"

:

"Invalid email format"

}

]

}

}

Step 5: Pagination

Query parameters

:

GET /api/v1/users?page=2&limit=20&sort=-created_at&filter=role:admin

Response with pagination

:

{

"data"

:

[

...

]

,

"pagination"

:

{

"page"

:

2

,

"limit"

:

20

,

"total"

:

100

,

"pages"

:

5

}

,

"links"

:

{

"self"

:

"/api/v1/users?page=2&limit=20"

,

"first"

:

"/api/v1/users?page=1&limit=20"

,

"prev"

:

"/api/v1/users?page=1&limit=20"

,

"next"

:

"/api/v1/users?page=3&limit=20"

,

"last"

:

"/api/v1/users?page=5&limit=20"

}

}

Step 6: Authentication

Options

:

JWT (JSON Web Tokens)

OAuth 2.0

API Keys

Session-based

Example with JWT

:

GET /api/v1/users

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Step 7: Versioning

URL versioning

(recommended):

/api/v1/users

/api/v2/users

Header versioning

:

GET /api/users

Accept: application/vnd.api+json; version=1

Step 8: Documentation

Create OpenAPI 3.0 specification:

openapi

:

3.0.0

info

:

title

:

User Management API

version

:

1.0.0

description

:

API for managing users

servers

:

-

url

:

https

:

//api.example.com/v1

paths

:

/users

:

get

:

summary

:

List users

parameters

:

-

name

:

page

in

:

query

schema

:

type

:

integer

default

:

1

-

name

:

limit

in

:

query

schema

:

type

:

integer

default

:

20

responses

:

'200'

:

description

:

Successful response

content

:

application/json

:

schema

:

type

:

object

properties

:

data

:

type

:

array

items

:

$ref

:

'#/components/schemas/User'

post

:

summary

:

Create user

requestBody

:

required

:

true

content

:

application/json

:

schema

:

$ref

:

'#/components/schemas/UserCreate'

responses

:

'201'

:

description

:

User created

content

:

application/json

:

schema

:

$ref

:

'#/components/schemas/User'

components

:

schemas

:

User

:

type

:

object

properties

:

id

:

type

:

integer

name

:

type

:

string

email

:

type

:

string

format

:

email

created_at

:

type

:

string

format

:

date

-

time

UserCreate

:

type

:

object

required

:

-

name

-

email

properties

:

name

:

type

:

string

email

:

type

:

string

format

:

email

Best practices

Consistency

Use consistent naming, structure, and patterns

Versioning

Always version your APIs from the start

Security

Implement authentication and authorization

Validation

Validate all inputs on the server side

Rate limiting

Protect against abuse

Caching

Use ETags and Cache-Control headers

CORS

Configure properly for web clients

Documentation

Keep docs up-to-date with code

Testing

Test all endpoints thoroughly

Monitoring

Log requests and track performance Common patterns Filtering : GET /api/v1/users?role=admin&status=active Sorting : GET /api/v1/users?sort=-created_at,name Field selection : GET /api/v1/users?fields=id,name,email Batch operations : POST /api/v1/users/batch { "operations": [ {"action": "create", "data": {...}}, {"action": "update", "id": 123, "data": {...}} ] } GraphQL alternative If REST doesn't fit, consider GraphQL: type User { id : ID ! name : String ! email : String ! posts : [ Post ! ] ! createdAt : DateTime ! } type Query { users ( page : Int , limit : Int ) : [ User ! ] ! user ( id : ID ! ) : User } type Mutation { createUser ( input : CreateUserInput ! ) : User ! updateUser ( id : ID ! , input : UpdateUserInput ! ) : User ! deleteUser ( id : ID ! ) : Boolean ! } References OpenAPI Specification REST API Tutorial GraphQL Best Practices HTTP Status Codes Examples Example 1: Basic usage Example 2: Advanced usage