RFC - API Documentation Guidelines

[green-arrow]

This RFC is being created in response to the discussion started in #461. It is also related to PR #458.

When documenting the API with API blueprint, we need to come up with standards on how to format the documentation file.

General Guidelines

Always use double spacing when adding new lines to the blueprint. The only exception is when declaring data structures, which are further detailed below.

Authorization

When declaring that an endpoint is for authorized users only, we should declare the appropriate authorization header as follows:

+ Headers

  Authorization: Bearer <access_token>

Content-Type Negotiation

All requests should state that the client must specify a Content-Type of application/vnd.api+json, in accordance with the JSON API spec.

Data Structures

Data structures should be named to mirror the naming in the JSON API spec.

Example using the Comment resource:

Comment Response (object)
+ data(Comment Resource)

Comments Response (object)
+ data(array[Comment Resource])

Comment Resource (object)
+ include Comment Resource Identifier
+ attributes
  + body, markdown, created_at, etc
+ relationships
  + post
    + data(array[Post Resource Identifier])
    + links

Comment Resource Identifier (object)
+ id, type

Post Resource Identifier (object)
+ id, type

[joshsmith]

It would be good to clarify where in the API spec you're sourcing the conventions, and also to look through our existing blueprint to see what other types of objects we're missing from your example that would be renamed.

This process won't catch every edge case right now, but we at least have a good pool of real-world examples from our own project to discuss in the course of this conversation.

[green-arrow]

@JoshSmith what do you mean by clarify where in the API spec I'm sourcing the conventions? Like where did I come up with the convention?

In that case, the double spacing came from #458.

As for other types of objects, the kinds I'm seeing are:

Errors (conflict, 4xx errors like not found, etc) OAuth Grant

Maybe it would be good to separate out the resource data structures from these other more generic structures?

[christopherstyles]

A little late to the conversation, but I love where this is going. Good call on mirroring json-api, makes a lot of sense 👍

[begedin]

:+1: For me as well. I wen't a bit overboard with objects in my PR. This is a nice balance and the naming is clear.

The only trouble I'm seeing (and I'm having that in my PR as well, are "reduced" objects we use in requests. For example, in a POST request, our Comment Resource

• does not have an ID
• it only supports and requires the "markdown" attribute. Nothing else can be assigned by the user. If we add more attributes, the API wont fail, but those will be ignored
• it only supports and requires the post relationship. user relationship is ignored and assigned as current user API-side, as are comment user mentions

Any ideas on how we might be able to handle that in a nice way? I guess if there's little repetition of cases like that, we can just create them individually for now.

[christopherstyles]

In case anyone else comes across this: if you have an attribute with an underscore _ and its value also has an underscore _, the example text won’t render correctly in the UI. Here’s an example:

+ state_transition: `signed_up` (string, optional)

The output will look something like this:

Instead, you have to escape the attribute name with backticks, like this:

+ `state_transition`: `signed_up` (string, optional)

…so that it renders properly:

This was discussed in https://github.com/apiaryio/api-blueprint/issues/224#issuecomment-119135158

[joshsmith]

@begedin doesn't the comment resource have an id due to include Comment Resource Identifier?

[joshsmith]

@begedin I think we handle individually now at cost of repetition and break it down further if needed.

[joshsmith]

Does someone want to take on adding documentation for this in a pull request, or possibly just adding this to the wiki to save some time?

[christopherstyles]

After much scratching-of-the-head over some really odd behavior (data structures with child attributes displaying as siblings, disappearing sections, etc) when using 2-space indentation, I think we should make it a general rule to indent all things with 4 spaces. It’s how they format indents in their examples. Switching to 4-space indentation led to much more predictable behavior.