Comments (9)
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 usingDELETE
operations when the API is expected to perform an actual delete? Could aDELETE
operation be provided for a period of time? - Use of status
200
on POST: Is there any historical reason for always using200
and returning an empty message/body vs. using201
or204
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 return404 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/orchannel
validate the format of the inputs and some do not, as such400 INVALID_ARG_TOPIC
or400 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.
Related Issues (14)
- nsqio move HOT 3
- nsqlookupd is missing a bunch of http api documentation HOT 4
- docs: /put should now /pub in quick start HOT 2
- docs: not updated for v1.0.0-compact changes
- docs: add /ping endpoint HOT 1
- docs: clarify when topics are created automatically HOT 10
- docs: nsqd durable restart/reload semantics HOT 3
- docs: missing ephemeral topics HOT 3
- docs: even more benchmarks HOT 3
- docs: more production users?!?! HOT 11
- Documentation: Quickstart opens nsqadmin at a different port and instructs to open at a different one. HOT 2
- docs:add more detail about nsqlookupd http api
- doc: the default value of heartbeat_interval wrong HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from nsqio.github.io.