RFC - API Documentation Guidelines

[green-arrow]

RFC - API Documentation Guidelines

[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.

[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]

👍 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 apiaryio/api-blueprint#224 (comment)

[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?