geertj / restful-api-design Goto Github PK

I've read these docs and they are very useful. However the Content Types section seems a bit unclear, even after reading the Forms section as well. In Content Types you suggest it is best to use "application/x-resource+format" and "application/x-collection+format" as content types and have nothing more specific than that. The Forms section makes sense as far as a generic way to define form input, but how are clients to know what fields/properties they might get from a resource and what they can do with it? This is still a point of confusion in your approach for me.

Note: all these content types use the “x-” experimental prefix that is allowed by RFC2046.

"X-" prefix of HTTP headers is deprecared, see RFC6648.

Hey!

I'd like to give REST-ful API Design a read, but prefer to do so through a PDF to make annotations on. Would you mind providing some precompiled PDFs (and possibly other formats for others)? I'm not so familiar with getting all of this Python stuff prepped and TeX ready etc. I assume you've got it all on your machine, so it's probably a lot easier for you to run make pdf. :-)

Thanks!

From bf8f6221a19c1256540f28bc82692469255323e4 Mon Sep 17 00:00:00 2001
From: Ralph Giles [email protected]
Date: Sat, 13 Aug 2011 21:11:11 -0700
Subject: [PATCH] Remove an spurious comma.

The first comma sets of the initial phrase, it doesn't start a

phrase in apposition.

scope.rst | 2 +-
1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/scope.rst b/scope.rst
index aed56fa..d697db3 100644
--- a/scope.rst
+++ b/scope.rst
@@ -34,7 +34,7 @@ this API. Maybe the application has a GUI, and you have a requirement to add a
programmatic interface to it. Or maybe the application was designed under the
assumption that it would be accessed only via the API you are designing.

-Like any application, the application for which the API is to be created,
+Like any application, the application for which the API is to be created
contains state. That state is dynamic, and will change due to various
operations that are executed on it. This state, and the operations on it, need

to be modeled and exposed, and will form the API you are designing.

1.7.6