docs: openapi specs about nsqio.github.io HOT 9 OPEN

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

from nsqio.github.io.

Screen caps in HTML format

from nsqio.github.io.

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?

from nsqio.github.io.

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.

from nsqio.github.io.

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

from nsqio.github.io.

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?

from nsqio.github.io.

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

from nsqio.github.io.

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.

from nsqio.github.io.

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

from nsqio.github.io.