HTTP API Design Guide | Hacker News Reader

HTTP API Design Guide

github.com

50 pointsD_Guidi8 comments

Please pardon my ignorance, but I am building a REST API using ASP.Net MVC 5 and Web API 2.0. I am not very clear on the following, can someone please help me with these recommendations in the Guide.

1) "Require TLS": How do I implement this for my Web API Project? Also what exactly does the author mean by saying "Require TLS". Is it achieved by using some kind of API Key+Token, or by using SSL for all communication, or is it something else?

2) "Responses - Provide resource (UU)IDs.". I have AutoIDs in all my tables for all the resources that are exposed as endpoints over HTTP. Is it ok to use this internal AutoID PK (PrimaryKey) value as id for the endpoints (ex: Updating a Resource by ID etc) or should I use a different ID field? Reason for asking is, I've been told by many people that "It's not good practice to expose your internal PK IDs anywhere to the outside world.".

3) "Keep JSON minified in all responses" - How can I do this in .Net / Web API? Are there libraries that already do this, or do I need to roll one from scratch.

Thank you!!!

Thank for asking these questions. I was wondering some of the same things.

Also: Has anyone done versioning with the Accepts header, and how did you do it on ASP.net?

To answer your first two questions:

1. TLS is the successor to SSL; setup your webserver with a certificate and redirect web traffic from HTTP to HTTPS.

2. UUIDs have some advantages over database primary keys; they are hard to guess; they can be generated on multiple machines without duplication. You could extend your current table with an extra column called public_id.

> and redirect web traffic from HTTP to HTTPS.

The original post [advises against this][1]:

> Redirects are discouraged since they allow sloppy/bad client behaviour without providing any clear gain. Clients that rely on redirects double up on server traffic and render TLS useless since sensitive data will already have been exposed during the first call.

[1]: https://github.com/interagent/http-api-design#require-tls

Most of these points seem well-thought out, but the pagination system using Content-Range headers seems a little bit quirky.

GitHub are using Link headers which seems more in keeping with the typical web approach of pagination:

https://developer.github.com/v3/#pagination

Does anyone have any real world experience with either of these approaches?

I am not sure about "Provide full resources where available". Why do we need to return everything with DELETE request? Client is supposed to know what to be deleted, so the response seems redundant.

I agree. If the DELETE is successful, the full resource should be null, so it would make sense to send a 204 with no content.

Consider this a request to delete an item from a users shopping cart:

DELETE /api/users/1234/cart/5678

I would expect this response to return the cart resource so client does not have to issue a GET /api/users/1234/cart request.

Reply on news.ycombinator.com