Who is the API Documentation Audience?

When you write API documentation, you write for the API developer. When it comes to API documentation, developers focus on two things:

• What requests look like (you want the server to understand it)
• What responses look like (you want to make sense of the data)

Supposed that my endpoint is located here:

https://hostname:port/base/movies

Simple Request

I want to get a list of movies, so how do I get this result?

GET /movies

Simple Response

I want to keep the example simple, so let’s assume that I only have 3 movies with an id, title, and year.

Here is an example response from this simple request:

{
"result": {
           "id":1,
           "title":"The Godfather",
           "year":1972
          }
          {
           "id":2,
           "title":"The Shawshank Redemption",
           "year":1994
          }
          {
           "id":3,
           "title":"Raging Bull",
           "year":1980
          }
          "status":"SUCCESS"
}

So what happened? 

1. I wanted to GET a list of my movies
2. I got my list of movies

Now the API developer can use this information for whatever purpose, such as an UI option that lists all movies.

Using Swagger for API Documentation

Swagger provides an amazing standard to author and test elegant API documentation. I have used Swagger on several projects, and I won an STC award for my API content.

Swagger Usage Example

I am testing a new Swagger plugin for WordPress using their Petstore example. I will update with my own example API documentation after I test the plugin and play with my JSON a bit.