

HTTP API Design Guide - D_Guidi
https://github.com/interagent/http-api-design

======
justboxing
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!!!

~~~
namsral
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.

~~~
matt_kantor
> 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](https://github.com/interagent/http-api-design#require-tls)

------
glenscott1
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](https://developer.github.com/v3/#pagination)

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

------
kimh
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.

~~~
hermanradtke
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.

