11 ms·

Documenting APIs

54 points by nalgeon 5y ago

remram 5y ago
> In a nutshell, REST APIs (which are a type of web API) involve requests and responses, not too unlike visiting a web page. You make a request to a resource stored on a server, and the server responds with the requested information. The protocol used to transport the data is HTTP. That would be an "HTTP API" pal. I know there's disagreement about what the REST constraints exactly are, and how strict we should be about it. The word has been thrown around for long enough that the meaning diluted. But to truly not know there's meaning at all... Like saying "writing code is called DevOps".
- omegalulw 5y ago
  Other than normal CDN stuff, are REST APIs even common today? IMO everyone wants to track users, sell targeted ads etc which requires maintaining state and eventually you diverge from REST.
  - remram 5y ago
    HTTP APIs are very common, I don't think anybody is trying to track users through them. I don't think whether they are REST or not makes any difference for tracking purposes, the client can always include a user/session ID.
languagehacker 5y ago
I like artifact-driven API design. If you must use REST, Swagger is a pretty decent way to get your API fully set up with everything but the business logic. Personally, I love GraphQL's Schema Definition Language. The whole thing is designed to explicitly declare data types and how to query for and operate on them, we with plenty of room for building documentation in along the way. Sadly, many popular implementations don't start with the SDL, but an SDL can be generated through those, and the good ones are smart enough to pull in documentation from code comments or addordances in their DSL.
- dpritchett 5y ago
  Agreed! I like grpc for the same reason. If I need to work with REST, a schema-first approach is ideal as it means various client, server, validation, and documentation dimensions are in sync by default. I get why folks often come at it from the other end and just layer some swagger annotations on top of their existing server code — lack of experience, the dynamicist’s mistrust of typing in general, or maybe they’re in a niche stack without a workable binding generator. Still, it’s better for everyone if the API provider can pull off the artifact-driven approach.
- legutierr 5y ago
  Are you aware of anything like Swagger or SDL but for JSON RPC? I've been looking, but haven't come across anything that can generate documentation from code, or generate code from documentation, the way that you can with Swagger.

54 points by nalgeon 5y ago

> In a nutshell, REST APIs (which are a type of web API) involve requests and responses, not too unlike visiting a web page. You make a request to a resource stored on a server, and the server responds with the requested information. The protocol used to transport the data is HTTP. That would be an "HTTP API" pal. I know there's disagreement about what the REST constraints exactly are, and how strict we should be about it. The word has been thrown around for long enough that the meaning diluted. But to truly not know there's meaning at all... Like saying "writing code is called DevOps".

omegalulw 5y ago
Other than normal CDN stuff, are REST APIs even common today? IMO everyone wants to track users, sell targeted ads etc which requires maintaining state and eventually you diverge from REST.
- remram 5y ago
  HTTP APIs are very common, I don't think anybody is trying to track users through them. I don't think whether they are REST or not makes any difference for tracking purposes, the client can always include a user/session ID.

languagehacker 5y ago

I like artifact-driven API design. If you must use REST, Swagger is a pretty decent way to get your API fully set up with everything but the business logic. Personally, I love GraphQL's Schema Definition Language. The whole thing is designed to explicitly declare data types and how to query for and operate on them, we with plenty of room for building documentation in along the way. Sadly, many popular implementations don't start with the SDL, but an SDL can be generated through those, and the good ones are smart enough to pull in documentation from code comments or addordances in their DSL.

dpritchett 5y ago
Agreed! I like grpc for the same reason. If I need to work with REST, a schema-first approach is ideal as it means various client, server, validation, and documentation dimensions are in sync by default. I get why folks often come at it from the other end and just layer some swagger annotations on top of their existing server code — lack of experience, the dynamicist’s mistrust of typing in general, or maybe they’re in a niche stack without a workable binding generator. Still, it’s better for everyone if the API provider can pull off the artifact-driven approach.
legutierr 5y ago
Are you aware of anything like Swagger or SDL but for JSON RPC? I've been looking, but haven't come across anything that can generate documentation from code, or generate code from documentation, the way that you can with Swagger.