API Documentation Sample: Blog Posts API

This is a sample documentation for a fictional blog posts API

Overview

The Blog Posts API allows developers to create, retrieve, update, and delete blog posts for a simple content-driven web application.
It is designed for products that need to manage written content such as blogs, newsletters, or knowledge bases.

All requests and responses use JSON.

Base URL

https://api.example.com/v1

Authentication

This API uses Bearer token authentication.

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

Authorization: Bearer YOUR_API_KEY

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

---

Create a Blog Post

Creates a new blog post.

POST /posts

Headers

{
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}

Request Body

{
  "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.

GET /posts

Header

{
  "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.

GET /posts/{id}

Header

{
  "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.

PUT /posts/{id}

Headers

{
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}

Request Body

{
  "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.

DELETE /posts/{id}

Header

{
  "Authorization": "Bearer YOUR_API_KEY"
}

Response

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

Error Responses

All error responses follow a consistent structure.

{
  "error": "Unauthorized",
  "message": "Invalid API key provided."
}

Getting Started

• Obtain an API key

• Add the key to the Authorization header

• Make your first request using the /posts endpoint