Add API reference template and guide #252
Conversation
There was a problem hiding this comment.
This template and guide is looking very good, authorative and valuable. My comments are mostly costmetic. Some are questions which we should raise with the good docs #template-style-guide group for discussion and decision.
I'm not an expert in API Docs, and hope that there will be others who can review from that perspective.
Suggestion: Re presenting a v1 and v2 version of the template and guide, I suggest that we only present the final version (which will be the final version in our repository). People can find the old version from an older branch.
| @@ -0,0 +1,204 @@ | |||
| # API Reference | |||
There was a problem hiding this comment.
Shouldn't this line be a variable for the actual reference page's title? Something like: # {page title, ex: "Send a message" or "POST /message"}
There was a problem hiding this comment.
question: Was there a specific motivation to go with this template format, rather than an OpenAPI specification?
There was a problem hiding this comment.
@csmeyns I think this template is meant for people manually writing an API reference page, rather than generating it from a spec. Not everyone has the expertise or toolset in their project to work from OAS or similar. But we should probably at least mention the OAS option as an alternative method for generating the page, maybe at the very beginning of the guide page.
|
|
||
| ## Overview | ||
|
|
||
| This reference describes the Application Program Interfaces (APIs) that help you {access | customize | program} {product}'s {features | functionality}. |
There was a problem hiding this comment.
I don't think it's necessary to define what an API is here. I could be wrong, but I think most people using an API reference page are going to have to know what an API is to get anything out of it. If you do keep the definition, use "Application Programming Interface" as the definition (see https://en.wikipedia.org/wiki/API). I would rewrite this sentence to say something like "Use this API to {describe what the user can do with the API here}."
|
|
||
| ### Base URL | ||
|
|
||
| The APIs referenced in this documentation use the following base URL: |
There was a problem hiding this comment.
The copy here seems redundant, the sub-header provides enough explanation.
| The APIs referenced in this documentation use the following base URL: | ||
|
|
||
| ``` | ||
| https://api.example.com |
There was a problem hiding this comment.
I would wrap the example URL in curly brackets like so:
{example: https://api.example.com}
|
|
||
| ### Authorization | ||
|
|
||
| All requests to the API must be authenticated and authorized before they can access or manage resources on the {environment | platform}. |
There was a problem hiding this comment.
This seems a bit wordy to me. I would just say, "Authentication and authorization {is / is not} required for requests to this API. Supported authentication methods are:
{
- Basic
- Digest
- O-Auth
}
"
|
|
||
| All requests to the API must be authenticated and authorized before they can access or manage resources on the {environment | platform}. | ||
|
|
||
| The {product} API uses the `{auth_type}` authorization type. |
|
|
||
| The {product} API uses the `{auth_type}` authorization type. | ||
|
|
||
| You can authenticate your requests by using {authentication type and method}. |
|
|
||
| You can authenticate your requests by using {authentication type and method}. | ||
|
|
||
| For example: |
There was a problem hiding this comment.
Example request with {Basic, Digest, etc.} authentication:
| For example: | ||
|
|
||
| ``` | ||
| {EXAMPLE} |
There was a problem hiding this comment.
It would be helpful for the author to show an actual example request, say generated in Postman. Something like:
GET /my-endpoint
Content-Type: application/json
Authorization: Basic 123456789frefr=
Host: my-url.com
| ``` | ||
|
|
||
|
|
||
| API requests without valid authentication will fail with a status of `{error_code}`. |
There was a problem hiding this comment.
I would probably just cover this in an errors section, if at all. REST API unauthorized requests have a standard response HTTP status code of 401, and API documentation doesn't typically cover standard error codes. You would document the error only if it is non-standard in some way, such as if it returns a custom payload or uses a non-standard HTTP code.
| API requests without valid authentication will fail with a status of `{error_code}`. | ||
|
|
||
|
|
||
| ### Versioning |
There was a problem hiding this comment.
I would changee this to:
Version
And then just list the version number. Separate versions of APIs should have entirely separate documentation sets, in my opinion. You can even version your documentation to match the API versions.
|
|
||
| ### Versioning | ||
|
|
||
| {This section is optional.} |
There was a problem hiding this comment.
I would delete all of the copy in this section and just have:
{Provide version number using semantic versioning or whatever your versioning scheme is, for example: 0.0.1}
|
|
||
| The {product} APIs use a {strategy_name} rate limiting strategy. The maximum number of requests allowed to access a {resource | endpoint |..} is {number} requests per {time period}. | ||
|
|
||
| If the number of requests exceeds that limit, an HTTP `429 Too Many Request` error is returned. |
There was a problem hiding this comment.
Remove this section or change it to cover non-standard responses. If the HTTP request is standard 429, it doesn't need to be covered in the documentation. You only need to document custom payloads or non-standard HTTP codes for error states.
| For example: | ||
|
|
||
| ``` | ||
| {EXAMPLE} |
There was a problem hiding this comment.
question: Why is EXAMPLE all uppercase? Two other uses of this below.
|
|
||
| | Query parameter | Type | Required? | Description | | ||
| |-----------------|------|-----------|-----------------------------------------| | ||
| | {pageSize} | int | Optional | {The number of items to be returned in a single request. The default value is 20.} | |
There was a problem hiding this comment.
Suggestion: the default value should be a variable.
|
|
||
| | Header parameter | Type | Required? | Description | | ||
| |------------------|--------|-----------|--------------------------------------| | ||
| | {Content-Type} | string | Required | {Media type of the resource. Must be object}. | |
| - Discuss the logic of grouping the API endpoints. Although grouping the endpoints by resource type is a common practice, as used in this template, it is also possible to group them by use case or other characteristics that better suit the user's needs. | ||
| - Conduct some user research about how the audience of your documentation would use the APIs. Identify the programming languages that your audience would most likely adopt to interact with your APIs. | ||
| - Explore the possibility of auto-generating the API references. | ||
| - Optimize the visual presentation of the API references by applying customized stylesheet, such as using syntax highlighting, table of contents, multi-column layout, etc. |
There was a problem hiding this comment.
suggestion: "applying a customized stylesheet"
|
|
||
| This section is optional. If applicable, use this section to describe the options and default values for dividing long API responses into pages. | ||
|
|
||
| :information_source: **Tip**: Your readers might not understand what "pagination" is, so it is wise to embed an explanation in the descriptive text. |
There was a problem hiding this comment.
suggestion: "so embed an explanation..."
|
|
||
| **Title** | ||
|
|
||
| Substitute the document title `{Resource Name}` with the actual name. The resource name usually uses the same naming convention as in the source code. |
There was a problem hiding this comment.
nitpick: you use "Resource name" capitalisation below.
|
|
||
| - Use fenced code blocks to make your code distinctive from other text blocks. | ||
| - Replace {METHOD} with the actual request method and capitalize all letters. For example, `POST`. | ||
| - In the {request_url} segment, start with a slash character `/` and only provide the URL path (the segment after the hostname). The base URL can be omitted if you already document it in the API overview. For example, `/v2/users`. |
There was a problem hiding this comment.
suggestion: "The base URL can be omitted if you have already documented it..."
|
|
||
| {This section is optional.} | ||
|
|
||
| Due to the potential very large result sets from API calls, responses {are | can be} returned as shorter pages. |
There was a problem hiding this comment.
| Due to the potential very large result sets from API calls, responses {are | can be} returned as shorter pages. | |
| Due to the potentially very large result sets from API calls, responses {are | can be} returned as shorter pages. |
|
|
||
| If the number of requests exceeds that limit, an HTTP `429 Too Many Request` error is returned. | ||
|
|
||
| ### HTTP status code |
There was a problem hiding this comment.
| ### HTTP status code | |
| ### HTTP status codes |
|
|
||
| ## {Endpoint name} | ||
|
|
||
| {Provide a one-line description of what the API does. Starts with a verb. For example, "retrieves a user".} |
There was a problem hiding this comment.
suggestion: It could be helpful to distinguish between the name (called 'summary' in the OpenAPI specification) and the description of the endpoint. In which case, the name of the endpoint would start with a verb in imperative mood, e.g. "Retrieve a user", while the description would start with a verb in indicative mood, e.g. "Retrieves a user by userID". Could that be an option here?
There was a problem hiding this comment.
^^^ This sounds like a good idea.
|
|
||
| | Path parameter | Type | Required? | Description | | ||
| |----------------|--------|-----------|------------------------------| | ||
| | {id} | string | Required | {Unique identifier of user.} | |
There was a problem hiding this comment.
| | {id} | string | Required | {Unique identifier of user.} | | |
| | {id} | string | Required | {Unique identifier of user} | |
| | {id} | string | Required | {Unique identifier of the user.} | | ||
| | {name} | string | Optional | {Name of the user.} | |
There was a problem hiding this comment.
| | {id} | string | Required | {Unique identifier of the user.} | | |
| | {name} | string | Optional | {Name of the user.} | | |
| | {id} | string | Required | {Unique identifier of the user} | | |
| | {name} | string | Optional | {Name of the user} | |
|
|
||
| ### About the "Introduction" section | ||
|
|
||
| Use this section to provide a high-level overview of your API set, including the main features, communication protocol, content types, organization, etc. |
There was a problem hiding this comment.
| Use this section to provide a high-level overview of your API set, including the main features, communication protocol, content types, organization, etc. | |
| Use the Introduction section to provide a high-level overview of your API set, including the main features, communication protocol, content types, and organization. |
|
|
||
| ### About the "Base URL" section | ||
|
|
||
| Base URL is a common segment to which the API endpoint paths are appended. Defining the base URL in this section reduces the effort to duplicate the segment in each endpoint reference. |
There was a problem hiding this comment.
| Base URL is a common segment to which the API endpoint paths are appended. Defining the base URL in this section reduces the effort to duplicate the segment in each endpoint reference. | |
| The base URL is a common segment to which the API endpoint paths are appended. Defining the base URL in this section reduces the effort to duplicate the segment in each endpoint reference. |
|
|
||
| :information_source: **Tips**: | ||
|
|
||
| - This section should only describe the technical specifications of the API authorization, such as parameters and token expiration. Details of how to authenticate should be documented in a separate how-to guide and be referred to as a link here. |
There was a problem hiding this comment.
| - This section should only describe the technical specifications of the API authorization, such as parameters and token expiration. Details of how to authenticate should be documented in a separate how-to guide and be referred to as a link here. | |
| - Only use this section to describe the technical specifications of the API authorization, such as parameters and token expiration. Details of how to authenticate can be documented in a separate how-to guide and be referred to as a link here. |
|
|
||
| This section is optional. If applicable, use this section to list the custom error types defined for the APIs. For easier navigation, you may provide each of the error definitions as a subsection. | ||
|
|
||
| ### Additional sections |
There was a problem hiding this comment.
suggestion: Perhaps other standard sections that could be included before the 'Additional sections' would be:
- License (specifying the license under which the API is released)
- Contact (specifying a contact for questions about the API)
|
|
||
| ## About the "API resource reference" section | ||
|
|
||
| The API resource reference section provides reference information for a subset of API endpoints that are grouped around a resource type. This section describes the data model of the resource type. |
There was a problem hiding this comment.
| The API resource reference section provides reference information for a subset of API endpoints that are grouped around a resource type. This section describes the data model of the resource type. | |
| Use the API resource reference section to provide reference information for a subset of API endpoints that are grouped around a resource type. You can use this section to describe the data model of the resource type. |
Template quality checklist
This quality checklist will eventually become a pull request template that every contributor needs to add to pull requests against the
templatesrepository.Pull request summary
This pull request add a new version of API reference template and the accompanying guide. Subdirectories were added (
api-reference/v1andapi-reference/v2) to distinguish the new files from previous ones.I am in the #emea-apac template working group. This template is created in collaboration with @gayathri-krishnaswamy @OphyBoamah @Chris-ganta, under the guidance of @camerons.
Template contributor checklist
IMPORTANT: The next three sections in this checklist should be filled out by the template contributor at the time they submit this request.
NOTE: Pull requests can only be merged when all boxes are checked.
Which issue does this pull request fix or reference?
This pull request:
Procedural requirements
Template set requirements
Template pull request reviewer checklist
IMPORTANT: The rest of the sections in this checklist should only be filled out by authorized Good Docs Project pull request reviewers. If you are the individual template contributor, do not fill out the rest of the fields or check the boxes.
NOTE: Pull requests can only be merged when all boxes are checked.
Mechanics and formatting requirements - PULL REQUEST REVIEWER ONLY
Overall usability - PULL REQUEST REVIEWER ONLY
Template file requirements - PULL REQUEST REVIEWER ONLY
Template guide requirements - PULL REQUEST REVIEWER ONLY
Deep dive requirements (optional) - PULL REQUEST REVIEWER ONLY
Template example requirements (optional) - PULL REQUEST REVIEWER ONLY