21–30 of 192 posts
Please drop fixed headers from web pages. If you want easy access to the top of the page use anchor links instead. On a laptop headers often take a big chunk of available screen. It just pisses me off every time I see a page with a fixed header. All your reader aren't using imacs...
Protocol Buffers...GraphQL...JSON-API...so many damn choices for API implementation! Next we need someone's essay of a blog post comparing/contrasting them all. Also, the Protocol Buffers link in the 3rd paragraph is 404.
Step 1) document the endpoints enough that outside developers can write their own clients. It took quite a bit of work for me to get a native Clojure client working to connect to the google cloud SDK. That was after wrestling with jar-hell around gRPC and calling the Java client from clojure, which is decidedly not pretty.
In these situations the best thing you can do is man-in-the-middle the HTTP requests from an existing client. That said, I've only ever had to do this when reversing private mobile API's. I can't believe a REST API from Google would be missing documentation of the raw HTTP endpoints?! That should be the first documentation of an API, before that of any specific client implementations.
Seems pretty good. Specifically this part of the guide is pretty well written: https://cloud.google.com/apis/design/resources . One thing that is surprising to me however is that their is no mention of using HTTP Status Codes in responses.
In typical HTTP REST services this transport/API error split makes it really easy to create client code which only needs to check two conditions - if the HTTP response code is 200 or not, and if the error value is set or not. You also don't have to shoehorn your error handling into the very limited set of errors provided by the HTTP protocol.
The other real-world advantage of this is that when you outgrow HTTP as the transport protocol for performance reasons this makes porting the API really easy to, e.g. protobuf RPC, or even raw TCP. The error is already defined as part of the API and you don't need to rewrite all your client code to deal with mapping multiple HTTP response codes to your new transport. It's good future proofing I've seen pay off in a at least a couple of real-world cases.
Bottom line - your server should always return HTTP status 200 and a separate API error response.
There's also a reasonable debate to have about whether non-error responses should also include an explicit "error" field with some default OK value. There may be good reasons to leave it out, e.g. if you want to save bandwidth, but I consider that a fairly insignificant point. For consistency my APIs always return a default OK error field on non-error responses - your mileage may vary.
Protocol Buffers...GraphQL...JSON-API...so many damn choices for API implementation! Next we need someone's essay of a blog post comparing/contrasting them all. Also, the Protocol Buffers link in the 3rd paragraph is 404.
Protocol Buffers...GraphQL...JSON-API...so many damn choices for API implementation! Next we need someone's essay of a blog post comparing/contrasting them all. Also, the Protocol Buffers link in the 3rd paragraph is 404.
If you're using a good framework like C# Web Api, you don't have to choose. Just implement them all by adding them to the pipeline and the framework will automatically serialize/deserialize based on the accept header.
Fantastic Read! But I am still looking for some books on good API-Design, anybody has any recommendations?
I am curious if anyone went to GraphQL without regrets?
Our application helps BigCos to understand if they pay people fairly and to run smart pay reviews. It's a relatively small codebase, ~100k LOC, but it's essential complexity is in managing and connecting dispersed data about employees and markets. GraphQL allows us to represent the natural links within this data, then the app frontends can present whatever business information is helpful in that page/sidebar/widget/card without separate endpoints.
With REST, we had the same problems with every feature: over/under-fetching, can't express relationships well, and can't evolve the schema easily. When we tried to work around these issues (e.g. "v2?fields=a,b,c"), we ended up with a poorly implemented subsection of GraphQL that's not benefiting from Facebook's experience. To compare to the world of databases, I view REST as a Key-Value protocol and GraphQL as an SQL with joins and functions. If all you need is to lookup a document, don't overcomplicate it. But if you need to express relations, you don't want to do that in userland.
The only advantage of REST is using a widely known standard with rich tooling and well-published "best practices" (that just try to work around REST limitations).
I don't see the actual guidelines, only Contents, Introduction and Conventions. On iOS Chrome /Safari. Also the fixed buttons overflows.