docs: openapi specs

[kenjones-cisco]

Provides clear documentation of each API and how to use them that is not tied to any specific vendor or technology.

There are tools that can consume the spec and generate the server component and the client component. go-swagger

Also tools for displaying the spec as html, and allows for interacting with the API if server is available.

nsqlookupd APIs as example:
https://gist.github.com/kenjones-cisco/5b36a7c54ddd548264178ca657e00bd7

To view an HTML representation of the example nsqlookupd spec provided, copy the yml file into the Swagger Editor to visually see what the documentation could look like.

Tasks:

• Create API spec for nsqd
• Create API spec for nsqlookupd
• Create API spec for nsqadmin
• Use specs for documentation on http://nsq.io

Considerations:

• Apply REST API patterns for APIs
• Evaluate code generation for Server components
• Evaluate code generation for Client components

References:

• Open APIs
• Specification
• Swagger Editor

[kenjones-cisco]

Screen caps in HTML format

[mreiferson]

It sounds promising for specification and documentation, I'm a bit weary of using it to generate the actual code though. In your experience, if we omitted code generation, would that compromise the effectiveness of this approach?

[kenjones-cisco]

The code generation is only one of the possible benefits, there are parts of what the code generation does that could be just used directly such that the spec is part of the run time to avoid the dreaded documentation and the code not being in alignment.

That is why I only put that under the Considerations list vs. the task list. I believe after creating the specs for the APIs and making use for the documentations is the first and most important part, then the second part could be making the spec an active part of the API implementation (like routing, validation, etc.).

After the task list is complete, then take a look at other ways the specs could be leveraged.

[kenjones-cisco]

@mreiferson When I submit a PR to add the specs, where in the directory structure would you want them placed?

Should the groups of APIs listed as deprecated (all those referred to as pre-v1) be included or would it be safe to leave those off?

[mreiferson]

Hmmm, spec directory for now? Let's leave off the deprecated endpoints.

[kenjones-cisco]

Questions based on initial nsqlookupd spec that was created.

• Use of POST vs. DELETE: Is there any historical reason for not using DELETE operations when the API is expected to perform an actual delete? Could a DELETE operation be provided for a period of time?
• Use of status 200 on POST: Is there any historical reason for always using 200 and returning an empty message/body vs. using 201 or 204 which mean success but avoids the unnecessary step or returning an empty message/body? Could this be changed such that all APIs that return empty message/body be changed as part of a future release?
• REST based API paths: Could a more REST based API paths be provided as part of a future release such that GET /channels would be GET /topics/{topic}/channels? (Other examples exist in the nsqlookupd spec)
• Some APIs that require topic as input do not return 404 TOPIC_NOT_FOUND and some do, should these be added to be consistent in responses when certain required inputs are not provided?
• Some APIs that require topic and/or channel validate the format of the inputs and some do not, as such 400 INVALID_ARG_TOPIC or 400 INVALID_ARG_CHANNEL, should these be added to be consistent in responses when certain inputs have a required format?
• On create APIs, should there be a check for if the topic or channel already exists? If so, is that an error?

[mreiferson]

Use of POST vs. DELETE: Is there any historical reason for not using DELETE operations when the API is expected to perform an actual delete? Could a DELETE operation be provided for a period of time?

No good reason, unfortunately.

Use of status 200 on POST: Is there any historical reason for always using 200 and returning an empty message/body vs. using 201 or 204 which mean success but avoids the unnecessary step or returning an empty message/body? Could this be changed such that all APIs that return empty message/body be changed as part of a future release?

Same here.

REST based API paths: Could a more REST based API paths be provided as part of a future release such that GET /channels would be GET /topics/{topic}/channels? (Other examples exist in the nsqlookupd spec)

Poke around the issues surrounding nsqio/nsq#330, I remember going back and forth a bit on this.

Some APIs that require topic as input do not return 404 TOPIC_NOT_FOUND and some do, should these be added to be consistent in responses when certain required inputs are not provided?

Perhaps it's not an error if the topic is not found (e.g. they result in a topic being created)?

[mreiferson]

Some APIs that require topic and/or channel validate the format of the inputs and some do not, as such 400 INVALID_ARG_TOPIC or 400 INVALID_ARG_CHANNEL, should these be added to be consistent in responses when certain inputs have a required format?

Yes, seems like good practice to validate the inputs on any endpoint that expects those parameters.

On create APIs, should there be a check for if the topic or channel already exists? If so, is that an error?

I don't think errors make sense for those ops.

[mreiferson]

moving this issue to https://github.com/nsqio/nsqio.github.io