API Documentation Sample: Blog Posts API

This is a sample documentation for a fictional blog posts API that allows developers to create, retrieve, update, and delete blog posts for a simple content-driven web application.

Getting Started

• Obtain an API key from your dashboard

• Add the key to the Authorization header

• Make your first request using the /posts endpoint

Base URL: https://api.iyanu.com/v1

---

Create a Blog Post

Creates a new blog post.

Endpoint: POST /posts

Request

  curl -X POST "https://api.iyanu.com/v1/posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Understanding APIs", "content": "APIs allow applications to communicate with each other."}'

Response

{
  "id": "post_12345",
  "title": "Understanding APIs",
  "content": "APIs allow applications to communicate with each other.",
  "created_at": "2026-01-05T12:00:00Z"
}

Retrieve All Blog Posts

Returns a list of all blog posts.

Endpoint: GET /posts

Request

curl -X GET "https://api.iyanu.com/v1/posts" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

[
  {
    "id": "post_12345",
    "title": "Understanding APIs",
    "created_at": "2026-01-05T12:00:00Z"
  },
  {
    "id": "post_67890",
    "title": "Getting Started with REST",
    "created_at": "2026-01-04T09:30:00Z"
  }
]

Retrieve a Single Blog Post

Returns a specific blog post by ID.

Endpoint: GET /posts/{id}

Request

curl -X GET "https://api.iyanu.com/v1/posts/post_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "post_12345",
  "title": "Understanding APIs",
  "content": "APIs allow applications to communicate with each other.",
  "created_at": "2026-01-05T12:00:00Z"
}

Update a Blog Post

Updates an existing blog post.

Endpoint: PUT /posts/{id}

Request

curl -X PUT "https://api.iyanu.com/v1/posts/post_12345" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Understanding REST APIs", "content": "REST APIs use standard HTTP methods for communication."}'

Response

{
  "id": "post_12345",
  "title": "Understanding REST APIs",
  "content": "REST APIs use standard HTTP methods for communication.",
  "updated_at": "2026-01-06T08:15:00Z"
}

Delete a Blog Post

Deletes a blog post permanently.

Endpoint: DELETE /posts/{id}

Request

curl -X DELETE "https://api.iyanu.com/v1/posts/post_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "message": "Blog post deleted successfully."
}

Error Responses

HTTP Status	Error Body Example
401 Unauthorized	{ "error": "Unauthorized", "message": "Invalid API key provided." }
403 Forbidden	{ "error": "Forbidden", "message": "You do not have permission to access this resource." }
404 Not Found	{ "error": "Not Found", "message": "Blog post does not exist." }
429 Too Many Requests	{ "error": "Too Many Requests", "message": "Rate limit exceeded. Try again later." }

All error responses follow a consistent structure. For example:

{
  "error": {
    "status": 401,
    "message": "invalid API key provided"
  }

Note

• This API uses Bearer token authentication.

• Include your API key in the Authorization header for every request.

• Requests without a valid API key will return a 401 Unauthorized response.