├── .gitignore
├── Makefile
├── conf.py
├── forms.rst
├── images
    ├── concepts.png
    ├── concepts.svg
    ├── scope.png
    └── scope.svg
├── index.rst
├── intro.rst
├── methods.rst
├── misc.rst
├── relationships.rst
├── resources.rst
├── scope.rst
└── urls.rst


/.gitignore:
--------------------------------------------------------------------------------
1 | _build
2 | _static
3 | _templates
4 | .*.swp
5 | 


--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
  1 | # Makefile for Sphinx documentation
  2 | #
  3 | 
  4 | # You can set these variables from the command line.
  5 | SPHINXOPTS    =
  6 | SPHINXBUILD   = sphinx-build
  7 | PAPER         =
  8 | BUILDDIR      = _build
  9 | 
 10 | # Internal variables.
 11 | PAPEROPT_a4     = -D latex_paper_size=a4
 12 | PAPEROPT_letter = -D latex_paper_size=letter
 13 | ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 14 | 
 15 | .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
 16 | 
 17 | help:
 18 | 	@echo "Please use \`make <target>' where <target> is one of"
 19 | 	@echo "  html       to make standalone HTML files"
 20 | 	@echo "  dirhtml    to make HTML files named index.html in directories"
 21 | 	@echo "  singlehtml to make a single large HTML file"
 22 | 	@echo "  pickle     to make pickle files"
 23 | 	@echo "  json       to make JSON files"
 24 | 	@echo "  htmlhelp   to make HTML files and a HTML help project"
 25 | 	@echo "  qthelp     to make HTML files and a qthelp project"
 26 | 	@echo "  devhelp    to make HTML files and a Devhelp project"
 27 | 	@echo "  epub       to make an epub"
 28 | 	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 29 | 	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
 30 | 	@echo "  text       to make text files"
 31 | 	@echo "  man        to make manual pages"
 32 | 	@echo "  changes    to make an overview of all changed/added/deprecated items"
 33 | 	@echo "  linkcheck  to check all external links for integrity"
 34 | 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 35 | 
 36 | clean:
 37 | 	-rm -rf $(BUILDDIR)/*
 38 | 
 39 | html:
 40 | 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 41 | 	@echo
 42 | 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 43 | 
 44 | dirhtml:
 45 | 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 46 | 	@echo
 47 | 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 48 | 
 49 | singlehtml:
 50 | 	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
 51 | 	@echo
 52 | 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 53 | 
 54 | pickle:
 55 | 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
 56 | 	@echo
 57 | 	@echo "Build finished; now you can process the pickle files."
 58 | 
 59 | json:
 60 | 	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
 61 | 	@echo
 62 | 	@echo "Build finished; now you can process the JSON files."
 63 | 
 64 | htmlhelp:
 65 | 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 66 | 	@echo
 67 | 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 68 | 	      ".hhp project file in $(BUILDDIR)/htmlhelp."
 69 | 
 70 | qthelp:
 71 | 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 72 | 	@echo
 73 | 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
 74 | 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
 75 | 	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Real-worldREST.qhcp"
 76 | 	@echo "To view the help file:"
 77 | 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Real-worldREST.qhc"
 78 | 
 79 | devhelp:
 80 | 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 81 | 	@echo
 82 | 	@echo "Build finished."
 83 | 	@echo "To view the help file:"
 84 | 	@echo "# mkdir -p $$HOME/.local/share/devhelp/Real-worldREST"
 85 | 	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Real-worldREST"
 86 | 	@echo "# devhelp"
 87 | 
 88 | epub:
 89 | 	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
 90 | 	@echo
 91 | 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 92 | 
 93 | latex:
 94 | 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 95 | 	@echo
 96 | 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
 97 | 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
 98 | 	      "(use \`make latexpdf' here to do that automatically)."
 99 | 
100 | latexpdf:
101 | 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
102 | 	@echo "Running LaTeX files through pdflatex..."
103 | 	make -C $(BUILDDIR)/latex all-pdf
104 | 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
105 | 
106 | text:
107 | 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
108 | 	@echo
109 | 	@echo "Build finished. The text files are in $(BUILDDIR)/text."
110 | 
111 | man:
112 | 	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
113 | 	@echo
114 | 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
115 | 
116 | changes:
117 | 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
118 | 	@echo
119 | 	@echo "The overview file is in $(BUILDDIR)/changes."
120 | 
121 | linkcheck:
122 | 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
123 | 	@echo
124 | 	@echo "Link check complete; look for any errors in the above output " \
125 | 	      "or in $(BUILDDIR)/linkcheck/output.txt."
126 | 
127 | doctest:
128 | 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
129 | 	@echo "Testing of doctests in the sources finished, look at the " \
130 | 	      "results in $(BUILDDIR)/doctest/output.txt."
131 | 


--------------------------------------------------------------------------------
/conf.py:
--------------------------------------------------------------------------------
  1 | # -*- coding: utf-8 -*-
  2 | #
  3 | # RESTful API Deisgn build configuration file, created by
  4 | # sphinx-quickstart on Mon Jul 25 09:21:34 2011.
  5 | #
  6 | # This file is execfile()d with the current directory set to its containing dir.
  7 | #
  8 | # Note that not all possible configuration values are present in this
  9 | # autogenerated file.
 10 | #
 11 | # All configuration values have a default; values that are commented out
 12 | # serve to show the default.
 13 | 
 14 | import sys, os
 15 | 
 16 | # If extensions (or modules to document with autodoc) are in another directory,
 17 | # add these directories to sys.path here. If the directory is relative to the
 18 | # documentation root, use os.path.abspath to make it absolute, like shown here.
 19 | #sys.path.insert(0, os.path.abspath('.'))
 20 | 
 21 | # -- General configuration -----------------------------------------------------
 22 | 
 23 | # If your documentation needs a minimal Sphinx version, state it here.
 24 | #needs_sphinx = '1.0'
 25 | 
 26 | # Add any Sphinx extension module names here, as strings. They can be extensions
 27 | # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 28 | extensions = []
 29 | 
 30 | # Add any paths that contain templates here, relative to this directory.
 31 | templates_path = ['_templates']
 32 | 
 33 | # The suffix of source filenames.
 34 | source_suffix = '.rst'
 35 | 
 36 | # The encoding of source files.
 37 | #source_encoding = 'utf-8-sig'
 38 | 
 39 | # The master toctree document.
 40 | master_doc = 'index'
 41 | 
 42 | # General information about the project.
 43 | project = u'RESTful API Design'
 44 | copyright = u'2011, Geert Jansen'
 45 | 
 46 | # The version info for the project you're documenting, acts as replacement for
 47 | # |version| and |release|, also used in various other places throughout the
 48 | # built documents.
 49 | #
 50 | # The short X.Y version.
 51 | version = '1.0'
 52 | # The full version, including alpha/beta/rc tags.
 53 | release = '1.0'
 54 | 
 55 | # The language for content autogenerated by Sphinx. Refer to documentation
 56 | # for a list of supported languages.
 57 | #language = None
 58 | 
 59 | # There are two options for replacing |today|: either, you set today to some
 60 | # non-false value, then it is used:
 61 | #today = ''
 62 | # Else, today_fmt is used as the format for a strftime call.
 63 | #today_fmt = '%B %d, %Y'
 64 | 
 65 | # List of patterns, relative to source directory, that match files and
 66 | # directories to ignore when looking for source files.
 67 | exclude_patterns = ['_build']
 68 | 
 69 | # The reST default role (used for this markup: `text`) to use for all documents.
 70 | #default_role = None
 71 | 
 72 | # If true, '()' will be appended to :func: etc. cross-reference text.
 73 | #add_function_parentheses = True
 74 | 
 75 | # If true, the current module name will be prepended to all description
 76 | # unit titles (such as .. function::).
 77 | #add_module_names = True
 78 | 
 79 | # If true, sectionauthor and moduleauthor directives will be shown in the
 80 | # output. They are ignored by default.
 81 | #show_authors = False
 82 | 
 83 | # The name of the Pygments (syntax highlighting) style to use.
 84 | pygments_style = 'sphinx'
 85 | highlight_language = 'guess'
 86 | 
 87 | # A list of ignored prefixes for module index sorting.
 88 | #modindex_common_prefix = []
 89 | 
 90 | 
 91 | # -- Options for HTML output ---------------------------------------------------
 92 | 
 93 | # The theme to use for HTML and HTML Help pages.  See the documentation for
 94 | # a list of builtin themes.
 95 | html_theme = 'agogo'
 96 | 
 97 | # Theme options are theme-specific and customize the look and feel of a theme
 98 | # further.  For a list of options available for each theme, see the
 99 | # documentation.
100 | #html_theme_options = {}
101 | 
102 | # Add any paths that contain custom themes here, relative to this directory.
103 | #html_theme_path = []
104 | 
105 | # The name for this set of Sphinx documents.  If None, it defaults to
106 | # "<project> v<release> documentation".
107 | #html_title = 'Thoughts on RESTful API Design'
108 | html_title = ''
109 | 
110 | # A shorter title for the navigation bar.  Default is the same as html_title.
111 | #html_short_title = None
112 | 
113 | # The name of an image file (relative to this directory) to place at the top
114 | # of the sidebar.
115 | #html_logo = None
116 | 
117 | # The name of an image file (within the static path) to use as favicon of the
118 | # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
119 | # pixels large.
120 | #html_favicon = None
121 | 
122 | # Add any paths that contain custom static files (such as style sheets) here,
123 | # relative to this directory. They are copied after the builtin static files,
124 | # so a file named "default.css" will overwrite the builtin "default.css".
125 | html_static_path = ['_static']
126 | 
127 | # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
128 | # using the given strftime format.
129 | #html_last_updated_fmt = '%b %d, %Y'
130 | 
131 | # If true, SmartyPants will be used to convert quotes and dashes to
132 | # typographically correct entities.
133 | #html_use_smartypants = True
134 | 
135 | # Custom sidebar templates, maps document names to template names.
136 | #html_sidebars = {}
137 | 
138 | # Additional templates that should be rendered to pages, maps page names to
139 | # template names.
140 | #html_additional_pages = {}
141 | 
142 | # If false, no module index is generated.
143 | #html_domain_indices = True
144 | 
145 | # If false, no index is generated.
146 | #html_use_index = True
147 | 
148 | # If true, the index is split into individual pages for each letter.
149 | #html_split_index = False
150 | 
151 | # If true, links to the reST sources are added to the pages.
152 | #html_show_sourcelink = True
153 | 
154 | # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
155 | #html_show_sphinx = True
156 | 
157 | # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
158 | #html_show_copyright = True
159 | 
160 | # If true, an OpenSearch description file will be output, and all pages will
161 | # contain a <link> tag referring to it.  The value of this option must be the
162 | # base URL from which the finished HTML is served.
163 | #html_use_opensearch = ''
164 | 
165 | # This is the file name suffix for HTML files (e.g. ".xhtml").
166 | #html_file_suffix = None
167 | 
168 | # Output file base name for HTML help builder.
169 | htmlhelp_basename = 'restful-api-design'
170 | 
171 | 
172 | # -- Options for LaTeX output --------------------------------------------------
173 | 
174 | # The paper size ('letter' or 'a4').
175 | #latex_paper_size = 'letter'
176 | 
177 | # The font size ('10pt', '11pt' or '12pt').
178 | #latex_font_size = '10pt'
179 | 
180 | # Grouping the document tree into LaTeX files. List of tuples
181 | # (source start file, target name, title, author, documentclass [howto/manual]).
182 | latex_documents = [
183 |   ('index', 'restful-api-design.tex', u'Thoughts on RESTful API design',
184 |    u'Geert Jansen', 'manual'),
185 | ]
186 | 
187 | # The name of an image file (relative to this directory) to place at the top of
188 | # the title page.
189 | #latex_logo = None
190 | 
191 | # For "manual" documents, if this is true, then toplevel headings are parts,
192 | # not chapters.
193 | #latex_use_parts = False
194 | 
195 | # If true, show page references after internal links.
196 | #latex_show_pagerefs = False
197 | 
198 | # If true, show URL addresses after external links.
199 | #latex_show_urls = False
200 | 
201 | # Additional stuff for the LaTeX preamble.
202 | #latex_preamble = ''
203 | 
204 | # Documents to append as an appendix to all manuals.
205 | #latex_appendices = []
206 | 
207 | # If false, no module index is generated.
208 | #latex_domain_indices = True
209 | 
210 | 
211 | # -- Options for manual page output --------------------------------------------
212 | 
213 | # One entry per manual page. List of tuples
214 | # (source start file, name, description, authors, manual section).
215 | man_pages = [
216 |     ('index', 'restful-api-design', u'Thoughts on RESTful API design',
217 |      [u'Geert Jansen'], 1)
218 | ]
219 | 


--------------------------------------------------------------------------------
/forms.rst:
--------------------------------------------------------------------------------
  1 | =====
  2 | Forms
  3 | =====
  4 | 
  5 | In this section, a solution is proposed to a usability issue that is present
  6 | in a lot of RESTful APIs today. This issue is that, without referring to
  7 | external documentation, an API user does not know what data to provide to
  8 | operations that take input. For example, the POST call is used to create a new
  9 | resource in a collection, and an API user can find out with the OPTIONS call
 10 | that a certain collection supports POST. However, he does not know what data
 11 | is required to create the new resource. So far, most RESTful APIs require the
 12 | user to refer to the API documentation to get that information. This violates
 13 | an important RESTful principle that APIs should be self-descriptive.
 14 | 
 15 | As far as I can see, this usability issue impacts two important use cases:
 16 | 
 17 | 1. A person is browsing the API, trying to use and learn it as he goes. The
 18 |    person can either be using a web browser, or a command-line tool like
 19 |    "curl".
 20 | 2. The development of a command-line or graphical interface to a RESTful API.
 21 |    Without a proper description of required input types, knowledge about
 22 |    these has to be encoded explicitly in the client. This has the disadvantage
 23 |    that new features are not automatically exposed, and that there are strict
 24 |    requirements around not making backwards incompatible changes.
 25 | 
 26 | When we look at the web, this issue doesn't exist. Millions of users interact
 27 | with all kinds of IT systems over the web at any given moment, and none of
 28 | them has to resort to API documentation to understand how to do that.
 29 | Interactions with IT systems on the web are all self-explanatory using
 30 | hypertext, and input is guided by forms.
 31 | 
 32 | In fact, forms are what I see as the solution here. But before I go into that,
 33 | let's look into two classes of solutions that have been proposed to
 34 | address this issue, and why I think they actually do not solve it.  The first
 35 | is using a type definition language like XMLSchema to describe the input
 36 | types, the second is using some kind of service description language like
 37 | WADL.
 38 | 
 39 | Type Definition
 40 | ===============
 41 | 
 42 | As alluded to in :doc:`resources`, some RESTful APIs use a type definition
 43 | language to provide information about how to construct request entities. In my
 44 | view this is a bad approach, and has the following issues:
 45 | 
 46 | 1. It creates a tight coupling between servers and clients.
 47 | 2. It still does not allow a plain web browser as an HTTP client.
 48 | 3. It does not help in the automatic construction of CLIs.
 49 | 
 50 | Often, XMLSchema is used as the type definition language. This brings in a few
 51 | more issues:
 52 | 
 53 | 1. XMLSchema is a horribly complicated specification on one side, but on the
 54 |    other side it can't properly solve the very common requirement of an
 55 |    unordered set of key:value pairs (Note that <xs:all> does not solve this.
 56 |    Its limitations make it almost useless.).
 57 | 2. Type definitions in XMLSchema are context-free. This means that you
 58 |    cannot just define one type, you need to define one type for PUT, one for
 59 |    POST, etc. And since one XML element can only have one type, this means
 60 |    you're PUTing a different element that you'd POST or GET. This breaks that
 61 |    "homogeneous collection" principle of REST.
 62 | 
 63 | Service Definition
 64 | ==================
 65 | 
 66 | `WADL <http://www.w3.org/Submission/wadl/>`_ is an approach to define a
 67 | service description language for RESTful APIs. It tries to solve the problem
 68 | by meticulously defining entry points and parameters to those. The problem I
 69 | have with WADL, is that it feels very non-RESTful. I can't see a lot of
 70 | difference between a method on a WADL resource, and an RPC entry point.
 71 | 
 72 | It would be possible to construct a more RESTful service description language.
 73 | It would focus on mapping the RESTful concepts of resource, collection,
 74 | relationships, and links. It would probably need a type definition language as
 75 | well to define the constraints on types for each method (again, PUT may have
 76 | different constraints than POST). There have been discussions in the RHEV-M
 77 | project on this.
 78 | 
 79 | In the end though, this approach also feels wrong. What I think is needed is
 80 | something that works like the web, where everything is self descriptive, and
 81 | guided only by the actual URL flow the user is going through, not by reference
 82 | to some external description.
 83 | 
 84 | Using Forms to Guide Input
 85 | ==========================
 86 | 
 87 | The right solution to guide client input in my view is to use forms. Note that
 88 | I'm using the word "forms" here in a generic sense, as an entity that guides
 89 | user input, and not necessarily equal to an HTML form.
 90 | 
 91 | In my view, forms need to specify three pieces of information:
 92 | 
 93 | 1. How to contact the target and format the input.
 94 | 2. A list of all available input fields.
 95 | 3. A list of constraints which which the input fields must comply.
 96 | 
 97 | HTML forms provide for #1 and #2, but not for #3 above. #3 is typically
 98 | achieved using client-side Javascript. Because Javascript is not normally
 99 | available to clients that use the API, we need to define another way to do
100 | validation. The approach I propose here is to define a form definition
101 | language that captures the information #1 through #3. A form expressed in this
102 | language can be sent over to the client as-is, in case the client understands
103 | the form language. It can also be translated into an HTML form with Javascript
104 | in case the client is a web browser.
105 | 
106 | Form Definition Language
107 | ------------------------
108 | 
109 | Our forms are defined as a special RESTful resource with type "form". This
110 | means they use the JSON data model, can be represented in JSON, YAML and XML
111 | according to the rules in :doc:`resources`.
112 | 
113 | Forms have their own content type.  This is listed in the table below:
114 | 
115 | ====  ============================
116 | Type          Content-Type
117 | ====  ============================
118 | Form  | application/x-form+json
119 |       | application/x-form+yaml
120 |       | application/x-form+xml
121 | ====  ============================
122 | 
123 | Rather than providing a formal definition, I will introduce the form
124 | definition language by using an example. Below is an example of a form that
125 | guides the the creation of a virtual machine. In YAML format::
126 | 
127 |   !form
128 |   method: POST
129 |   action: {url}
130 |   type: vm
131 |   fields:
132 |   - name: name
133 |     type: string
134 |     regex: [a-zA-Z0-9]{5,32}
135 |   - name: description
136 |     type: string
137 |     maxlen: 128
138 |   - name: memory
139 |     type: number
140 |     min: 512
141 |     max: 8192
142 |   - name: restart
143 |     type: boolean
144 |   - name: priority
145 |     type: number
146 |     min: 0
147 |     max: 100
148 |   constraints:
149 |   - sense: mandatory
150 |     field: name
151 |   - sense: optional
152 |     field: description
153 |   - sense: optional
154 |     field: cpu.cores
155 |   - sense: optional
156 |     field: cpu.sockets
157 |   - sense: optional
158 |     exclusive: true
159 |     constraints:
160 |     - sense: mandatory
161 |       field: highlyavailable
162 |     - sense: optional
163 |       field: priority
164 | 
165 | As can be seen the form consists of 3 parts: form metadata, field definitions,
166 | and constraints.
167 | 
168 | Form Metadata
169 | -------------
170 | 
171 | The form metadata is very simple. The following attributes are defined:
172 | 
173 | =========  ============================================================
174 | Attribute                           Description
175 | =========  ============================================================
176 | method     The HTTP method to use. Can be GET, POST, PUT or DELETE.
177 | url        The URL to submit this form to.
178 | type       The type of the resource to submit.
179 | =========  ============================================================
180 | 
181 | Fields
182 | ------
183 | 
184 | The list of available fields are specified using the "fields" attribute. This
185 | should be a list of field definitions. Each field definition has the following
186 | attributes:
187 | 
188 | =========  ===============================================================
189 | Attribute                           Description
190 | =========  ===============================================================
191 | name       The field name. Should be in dotted-name notation.
192 | type       One of "string", "number" or "boolean"
193 | min        Field value must be greater than or equal to this (numbers)
194 | max        Field value must be less than or equal to this (numbers)
195 | minlen     Minimum field length (strings)
196 | maxlen     Maximum field length (strings)
197 | regex      Field value needs to match this regular expression (strings)
198 | multiple   Boolean that indicates if multiple values are accepted (array).
199 | =========  ===============================================================
200 | 
201 | Constraints
202 | -----------
203 | 
204 | First we need to answer the question of what kind of constraints we want to
205 | express in our form definition language. I will start by mentioning that in my
206 | view, it is impossible to express each and every constraint on the client side. Some
207 | constraints for example require access to other data (e.g. when creating
208 | relationships), are computationally intensive, or even unknown to the API
209 | designer because they are undocumented for the application the API is written
210 | for. So in my view we need to find a good subset that is useful, without
211 | making it too complicated and without worrying about the fact that some
212 | constraints possibly cannot not be expressed.
213 | 
214 | This leads me to define the following two kinds of constraints, which in my
215 | view are both useful, as well as sufficient for our purposes:
216 | 
217 | 1. Constraints on individual data values.
218 | 2. Presence constraints on fields, i.e. whether a field is allowed or not
219 |    allowed, and if allowed, whether it is mandatory.
220 | 
221 | The constraints on data values are useful because CLIs and GUIs could use this
222 | information to help a user input data. For example, depending on the type, a
223 | GUI could render a certain field a checkbox, a text box, or a dropdown list.
224 | For brevity, constraints on individual data values are defined as part of the
225 | field definition, and were discussed in the previous section.
226 | 
227 | Presence constraints are also useful, as they allow an API user to generate a
228 | concise synopsis on how to call a certain operation to be used e.g. in CLIs.
229 | Presence constraints specify which (combination of) input fields can and
230 | cannot exist. Each presence constraint has the following attributes:
231 | 
232 | ===========  ============================================================
233 | Attribute                           Description
234 | ===========  ============================================================
235 | sense        One of "mandatory" or "optional"
236 | field        This constraint refers to a field.
237 | constraints  This constraint is a group with nested constraints.
238 | exclusive    This is an exclusive group (groups only).
239 | ===========  ============================================================
240 | 
241 | Either "field" or "constraints" has to be specified, but not both. A
242 | constraint that has the field attribute set is called a simple constraint. A
243 | constraint that has the constraints attribute set, is called a group.
244 | 
245 | Checking Constraints
246 | --------------------
247 | 
248 | Value constraints should be checked first, and should be checked only on
249 | non-null values.
250 | 
251 | After value constraints, the presence constraints should to be checked. This
252 | is a bit more complicated because the constraints are not only used for making
253 | sure that all mandatory fields exist, but also that no non-optional fields are
254 | present. The following algorithm should be used:
255 | 
256 | 1. Start with an empty list called "referenced" that will collect all
257 |    referenced fields.
258 | 2. Walk over all constraints in order. If a constraint is a group,  you need
259 |    to recurse into it, depth first, passing it the "referenced" list.
260 | 3. For every simple constraint that validates, add the field name to
261 |    "referenced".
262 | 4. In exclusive groups, matching stops at the first matching sub-constraint,
263 |    in which case the group matches. In non-exclusive groups, matching stops at
264 |    the first non-matching sub-constraint, in which case the group does not
265 |    match.
266 | 5. When matching a group, you need to backtrack to the previous value of
267 |    "referenced" in case the group does not match.
268 | 6. A constraint only fails if it is mandatory and it is a top-level
269 |    constraint. If a constraint fails, processing may stop.
270 | 7. When you've walked through all constraints, it is an error if there are
271 |    fields that have a non-null value but are not in the referenced list.
272 | 
273 | Building the Request Entity
274 | ---------------------------
275 | 
276 | After all constraints have been satisfied, a client should build a request
277 | entity that it will pass in the body of the POST, PUT or DELETE method.  In
278 | case the form was requested in JSON, YAML or XML format, it is assumed that
279 | the client is not a web browser, and the following applies:
280 | 
281 | First, a new resource is created of the type specified in the form metadata.
282 | Dotted field names should be interpreted as follows. Each dot creates a new
283 | object, and stores it under the name immediately left of the dot in its parent
284 | object. This means that the parent must be an object as well, which means it
285 | cannot correspond to a field definition with "multiple" set to "true" (which
286 | would make it a list). This resource is then represented in a format that the
287 | server supports, using the rules described in :doc:`resources`.
288 | 
289 | If a client requested a "text/html" representation of the form, it is assumed
290 | that the client is a web browser, and we assume the form will be processed as
291 | a regular HTML form. In this case:
292 | 
293 | * An HTML <form> should be generated, with an appropriate <input> element for
294 |   each field.
295 | * The HTML form's "method" attribute should be set to POST, unconditionally. In
296 |   case the RESTful form's method is not POST, the server should include a
297 |   hidden input element with the name "_method" to indicate to the server the
298 |   original method. (HTML does not support PUT or DELETE in a form).
299 | * The form's "enctype" should be set to "multipart/form-data" or
300 |   "application/x-www-form-urlencoded", as appropriate for the input elements.
301 | * A hidden field called "_type" is generated that contains the value of the
302 |   "type" attribute in the form metadata.
303 | * The server may generate Javascript and include that in the HTML to check the
304 |   value and presence constraints.
305 | 
306 | Linking to Forms
307 | ================
308 | 
309 | Forms are associated with resources and collections by link objects. The name
310 | of the link object defines the meaning of the form. The following standard
311 | forms names are defined:
312 | 
313 | ============  ==========  =============================
314 |    Name         Scope             Description
315 | ============  ==========  =============================
316 | form/search   collection  Form to search for resources
317 | form/create   collection  Form to create a new resource
318 | form/update   resource    Form to update a resource
319 | form/delete   resource    Form to delete a resource
320 | ============  ==========  =============================
321 | 


--------------------------------------------------------------------------------
/images/concepts.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/geertj/restful-api-design/b16658d0fcada422a8eb947e2609b72902042a5d/images/concepts.png


--------------------------------------------------------------------------------
/images/concepts.svg:
--------------------------------------------------------------------------------
  1 | <?xml version="1.0" encoding="UTF-8" standalone="no"?>
  2 | <!-- Created with Inkscape (http://www.inkscape.org/) -->
  3 | 
  4 | <svg
  5 |    xmlns:dc="http://purl.org/dc/elements/1.1/"
  6 |    xmlns:cc="http://creativecommons.org/ns#"
  7 |    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  8 |    xmlns:svg="http://www.w3.org/2000/svg"
  9 |    xmlns="http://www.w3.org/2000/svg"
 10 |    xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
 11 |    xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
 12 |    width="297mm"
 13 |    height="210mm"
 14 |    id="svg5318"
 15 |    version="1.1"
 16 |    inkscape:version="0.48.1 r9760"
 17 |    sodipodi:docname="concepts.svg"
 18 |    inkscape:export-filename="/home/geertj/Projects/restful-api-design/images/concepts.png"
 19 |    inkscape:export-xdpi="90"
 20 |    inkscape:export-ydpi="90">
 21 |   <defs
 22 |      id="defs5320" />
 23 |   <sodipodi:namedview
 24 |      inkscape:document-units="mm"
 25 |      pagecolor="#ffffff"
 26 |      bordercolor="#666666"
 27 |      borderopacity="1.0"
 28 |      inkscape:pageopacity="0.0"
 29 |      inkscape:pageshadow="2"
 30 |      inkscape:zoom="0.86831672"
 31 |      inkscape:cx="579.25863"
 32 |      inkscape:cy="380"
 33 |      inkscape:current-layer="layer1"
 34 |      id="namedview5322"
 35 |      showgrid="false"
 36 |      inkscape:window-width="1920"
 37 |      inkscape:window-height="1023"
 38 |      inkscape:window-x="0"
 39 |      inkscape:window-y="26"
 40 |      inkscape:window-maximized="1" />
 41 |   <metadata
 42 |      id="metadata5324">
 43 |     <rdf:RDF>
 44 |       <cc:Work
 45 |          rdf:about="">
 46 |         <dc:format>image/svg+xml</dc:format>
 47 |         <dc:type
 48 |            rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
 49 |         <dc:title></dc:title>
 50 |       </cc:Work>
 51 |     </rdf:RDF>
 52 |   </metadata>
 53 |   <g
 54 |      inkscape:label="Layer 1"
 55 |      inkscape:groupmode="layer"
 56 |      id="layer1">
 57 |     <rect
 58 |        style="fill:#ffffff;stroke:none"
 59 |        id="rect5959"
 60 |        width="1007.6968"
 61 |        height="529.76062"
 62 |        x="23.03307"
 63 |        y="31.220959" />
 64 |     <rect
 65 |        style="fill:#ececec;stroke:none"
 66 |        id="rect5957"
 67 |        width="166.98976"
 68 |        height="47.217793"
 69 |        x="413.4436"
 70 |        y="83.045364" />
 71 |     <text
 72 |        sodipodi:linespacing="125%"
 73 |        id="text5929"
 74 |        y="445.07632"
 75 |        x="771.42224"
 76 |        style="font-size:18px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
 77 |        xml:space="preserve"><tspan
 78 |          y="445.07632"
 79 |          x="771.42224"
 80 |          sodipodi:role="line"
 81 |          id="tspan5935">Sub-collections and</tspan><tspan
 82 |          y="467.57632"
 83 |          x="771.42224"
 84 |          sodipodi:role="line"
 85 |          id="tspan4975">Sub-resources</tspan></text>
 86 |     <rect
 87 |        ry="11.361756"
 88 |        y="198.81729"
 89 |        x="667.71729"
 90 |        height="140.12831"
 91 |        width="181.35007"
 92 |        id="rect5927"
 93 |        style="fill:#ffffff;stroke:#000000;stroke-width:1.14789677;stroke-miterlimit:4;stroke-dasharray:none" />
 94 |     <rect
 95 |        style="fill:#ffffff;stroke:#000000;stroke-width:1.14789677;stroke-miterlimit:4;stroke-dasharray:none"
 96 |        id="rect5925"
 97 |        width="181.35007"
 98 |        height="140.12831"
 99 |        x="677.71729"
100 |        y="208.81729"
101 |        ry="11.361756" />
102 |     <rect
103 |        ry="11.361756"
104 |        y="218.81729"
105 |        x="687.71729"
106 |        height="140.12831"
107 |        width="181.35007"
108 |        id="rect5923"
109 |        style="fill:#ffffff;stroke:#000000;stroke-width:1.14789677;stroke-miterlimit:4;stroke-dasharray:none" />
110 |     <rect
111 |        style="fill:#ffffff;stroke:#000000;stroke-width:0.72767680999999995;stroke-miterlimit:4;stroke-dasharray:none"
112 |        id="rect5327"
113 |        width="131.41174"
114 |        height="77.710701"
115 |        x="131.22688"
116 |        y="207.36234"
117 |        ry="6.3008685" />
118 |     <text
119 |        xml:space="preserve"
120 |        style="font-size:14px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
121 |        x="211.90425"
122 |        y="290.34299"
123 |        id="text5329"
124 |        sodipodi:linespacing="125%"><tspan
125 |          sodipodi:role="line"
126 |          id="tspan5331"
127 |          x="211.90425"
128 |          y="290.34299" /></text>
129 |     <rect
130 |        style="fill:none;stroke:#000000;stroke-width:0.58657074;stroke-miterlimit:4;stroke-dasharray:none"
131 |        id="rect5337"
132 |        width="241.05325"
133 |        height="212.52975"
134 |        x="94.256767"
135 |        y="134.69096"
136 |        ry="4.6631513" />
137 |     <text
138 |        xml:space="preserve"
139 |        style="font-size:18px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
140 |        x="155.47324"
141 |        y="174.02599"
142 |        id="text5339"
143 |        sodipodi:linespacing="125%"><tspan
144 |          sodipodi:role="line"
145 |          id="tspan5341"
146 |          x="155.47324"
147 |          y="174.02599">Collection</tspan></text>
148 |     <rect
149 |        ry="6.3008685"
150 |        y="217.36234"
151 |        x="141.22688"
152 |        height="77.710701"
153 |        width="131.41174"
154 |        id="rect5349"
155 |        style="fill:#ffffff;stroke:#000000;stroke-width:0.72767681;stroke-miterlimit:4;stroke-dasharray:none" />
156 |     <rect
157 |        style="fill:#ffffff;stroke:#000000;stroke-width:0.72767681;stroke-miterlimit:4;stroke-dasharray:none"
158 |        id="rect5351"
159 |        width="131.41174"
160 |        height="77.710701"
161 |        x="151.22688"
162 |        y="227.36234"
163 |        ry="6.3008685" />
164 |     <rect
165 |        ry="6.3008685"
166 |        y="237.36234"
167 |        x="161.22688"
168 |        height="77.710701"
169 |        width="131.41174"
170 |        id="rect5353"
171 |        style="fill:#ffffff;stroke:#000000;stroke-width:0.72767681;stroke-miterlimit:4;stroke-dasharray:none" />
172 |     <text
173 |        xml:space="preserve"
174 |        style="font-size:18px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
175 |        x="185.41623"
176 |        y="278.82645"
177 |        id="text5333"
178 |        sodipodi:linespacing="125%"><tspan
179 |          sodipodi:role="line"
180 |          id="tspan5335"
181 |          x="185.41623"
182 |          y="278.82645">Resource</tspan></text>
183 |     <rect
184 |        style="fill:#ffffff;stroke:#000000;stroke-width:0.72767681;stroke-miterlimit:4;stroke-dasharray:none"
185 |        id="rect5355"
186 |        width="131.41174"
187 |        height="77.710701"
188 |        x="428.71381"
189 |        y="262.08752"
190 |        ry="6.3008685" />
191 |     <text
192 |        sodipodi:linespacing="125%"
193 |        id="text5357"
194 |        y="303.55164"
195 |        x="452.90314"
196 |        style="font-size:18px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
197 |        xml:space="preserve"><tspan
198 |          y="303.55164"
199 |          x="452.90314"
200 |          id="tspan5359"
201 |          sodipodi:role="line">Resource</tspan></text>
202 |     <text
203 |        xml:space="preserve"
204 |        style="font-size:18px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
205 |        x="211.71864"
206 |        y="445.07632"
207 |        id="text5361"
208 |        sodipodi:linespacing="125%"><tspan
209 |          sodipodi:role="line"
210 |          id="tspan5363"
211 |          x="211.71864"
212 |          y="445.07632">A Collection with</tspan><tspan
213 |          sodipodi:role="line"
214 |          x="211.71864"
215 |          y="467.57632"
216 |          id="tspan5365">Resources</tspan></text>
217 |     <text
218 |        xml:space="preserve"
219 |        style="font-size:18px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
220 |        x="489.36981"
221 |        y="445.07632"
222 |        id="text5367"
223 |        sodipodi:linespacing="125%"><tspan
224 |          sodipodi:role="line"
225 |          id="tspan5369"
226 |          x="489.36981"
227 |          y="445.07632">A Singleton</tspan><tspan
228 |          sodipodi:role="line"
229 |          x="492.23505"
230 |          y="467.57632"
231 |          id="tspan5371">Resource </tspan></text>
232 |     <rect
233 |        ry="5.5922132"
234 |        y="138.14592"
235 |        x="634.74713"
236 |        height="254.87308"
237 |        width="279.33295"
238 |        id="rect5375"
239 |        style="fill:none;stroke:#000000;stroke-width:0.69147599;stroke-miterlimit:4;stroke-dasharray:none" />
240 |     <text
241 |        sodipodi:linespacing="125%"
242 |        id="text5377"
243 |        y="168.26772"
244 |        x="716.32849"
245 |        style="font-size:18px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
246 |        xml:space="preserve"><tspan
247 |          y="168.26772"
248 |          x="716.32849"
249 |          id="tspan5379"
250 |          sodipodi:role="line">Collection</tspan></text>
251 |     <rect
252 |        style="fill:#ffffff;stroke:#000000;stroke-width:1.14789677;stroke-miterlimit:4;stroke-dasharray:none"
253 |        id="rect5385"
254 |        width="181.35007"
255 |        height="140.12831"
256 |        x="697.71729"
257 |        y="228.81729"
258 |        ry="11.361756" />
259 |     <text
260 |        sodipodi:linespacing="125%"
261 |        id="text5387"
262 |        y="264.2814"
263 |        x="721.90662"
264 |        style="font-size:18px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
265 |        xml:space="preserve"><tspan
266 |          y="264.2814"
267 |          x="721.90662"
268 |          id="tspan5389"
269 |          sodipodi:role="line">Resource</tspan></text>
270 |     <rect
271 |        style="fill:#ffffff;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none"
272 |        id="rect5391"
273 |        width="145.80905"
274 |        height="79.164482"
275 |        x="718.45166"
276 |        y="278.91647"
277 |        ry="11.005226" />
278 |     <rect
279 |        style="fill:#000000;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none"
280 |        id="rect5393"
281 |        width="18.426456"
282 |        height="8.0615749"
283 |        x="734.57477"
284 |        y="321.25748"
285 |        ry="4.0307875" />
286 |     <rect
287 |        ry="4.0307875"
288 |        y="321.25748"
289 |        x="760.57477"
290 |        height="8.0615749"
291 |        width="18.426456"
292 |        id="rect5395"
293 |        style="fill:#000000;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none" />
294 |     <rect
295 |        style="fill:#000000;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none"
296 |        id="rect5397"
297 |        width="18.426456"
298 |        height="8.0615749"
299 |        x="760.57477"
300 |        y="333.25748"
301 |        ry="4.0307875" />
302 |     <rect
303 |        ry="4.0307875"
304 |        y="333.25748"
305 |        x="734.57477"
306 |        height="8.0615749"
307 |        width="18.426456"
308 |        id="rect5399"
309 |        style="fill:#000000;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none" />
310 |     <text
311 |        xml:space="preserve"
312 |        style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
313 |        x="742.63641"
314 |        y="301.13437"
315 |        id="text5401"
316 |        sodipodi:linespacing="125%"><tspan
317 |          sodipodi:role="line"
318 |          x="742.63641"
319 |          y="301.13437"
320 |          id="tspan5405">Sub- collection</tspan></text>
321 |     <text
322 |        xml:space="preserve"
323 |        style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
324 |        x="793.30908"
325 |        y="329.92566"
326 |        id="text5407"
327 |        sodipodi:linespacing="125%"><tspan
328 |          sodipodi:role="line"
329 |          id="tspan5409"
330 |          x="793.30908"
331 |          y="329.92566">Sub-</tspan><tspan
332 |          sodipodi:role="line"
333 |          x="793.30908"
334 |          y="344.92566"
335 |          id="tspan5411">resources</tspan></text>
336 |     <rect
337 |        style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:1,3;stroke-dashoffset:0"
338 |        id="rect5937"
339 |        width="904.18811"
340 |        height="337.57458"
341 |        x="57.512634"
342 |        y="72.610443"
343 |        ry="0" />
344 |     <text
345 |        xml:space="preserve"
346 |        style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
347 |        x="433.02173"
348 |        y="112.98836"
349 |        id="text5939"
350 |        sodipodi:linespacing="125%"><tspan
351 |          sodipodi:role="line"
352 |          id="tspan5941"
353 |          x="433.02173"
354 |          y="112.98836" /></text>
355 |     <text
356 |        xml:space="preserve"
357 |        style="font-size:18px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
358 |        x="424.96017"
359 |        y="111.23009"
360 |        id="text5943"
361 |        sodipodi:linespacing="125%"><tspan
362 |          sodipodi:role="line"
363 |          id="tspan5945"
364 |          x="424.96017"
365 |          y="111.23009">Resource Model</tspan></text>
366 |     <path
367 |        style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
368 |        d="m 427.26345,116.98836 140.50173,0"
369 |        id="path5955"
370 |        inkscape:connector-curvature="0" />
371 |   </g>
372 | </svg>
373 | 


--------------------------------------------------------------------------------
/images/scope.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/geertj/restful-api-design/b16658d0fcada422a8eb947e2609b72902042a5d/images/scope.png


--------------------------------------------------------------------------------
/images/scope.svg:
--------------------------------------------------------------------------------
  1 | <?xml version="1.0" encoding="UTF-8" standalone="no"?>
  2 | <!-- Created with Inkscape (http://www.inkscape.org/) -->
  3 | 
  4 | <svg
  5 |    xmlns:dc="http://purl.org/dc/elements/1.1/"
  6 |    xmlns:cc="http://creativecommons.org/ns#"
  7 |    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  8 |    xmlns:svg="http://www.w3.org/2000/svg"
  9 |    xmlns="http://www.w3.org/2000/svg"
 10 |    xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
 11 |    xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
 12 |    width="1052.3622"
 13 |    height="744.09448"
 14 |    id="svg2"
 15 |    version="1.1"
 16 |    inkscape:version="0.48.1 r9760"
 17 |    sodipodi:docname="scope.svg"
 18 |    inkscape:export-filename="/home/geertj/Projects/restful-api-design/images/scope.png"
 19 |    inkscape:export-xdpi="90"
 20 |    inkscape:export-ydpi="90">
 21 |   <defs
 22 |      id="defs4">
 23 |     <marker
 24 |        inkscape:stockid="Arrow1Mend"
 25 |        orient="auto"
 26 |        refY="0.0"
 27 |        refX="0.0"
 28 |        id="Arrow1Mend"
 29 |        style="overflow:visible;">
 30 |       <path
 31 |          id="path4071"
 32 |          d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
 33 |          style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none;"
 34 |          transform="scale(0.4) rotate(180) translate(10,0)" />
 35 |     </marker>
 36 |     <linearGradient
 37 |        id="linearGradient5296">
 38 |       <stop
 39 |          style="stop-color:#a0502c;stop-opacity:1;"
 40 |          offset="0"
 41 |          id="stop5298" />
 42 |       <stop
 43 |          id="stop5314"
 44 |          offset="1"
 45 |          style="stop-color:#a02c2c;stop-opacity:0.74901961;" />
 46 |     </linearGradient>
 47 |     <marker
 48 |        inkscape:stockid="Arrow1Lend"
 49 |        orient="auto"
 50 |        refY="0.0"
 51 |        refX="0.0"
 52 |        id="Arrow1Lend"
 53 |        style="overflow:visible;">
 54 |       <path
 55 |          id="path3957"
 56 |          d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
 57 |          style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none;"
 58 |          transform="scale(0.8) rotate(180) translate(12.5,0)" />
 59 |     </marker>
 60 |     <marker
 61 |        inkscape:stockid="Arrow1Lend"
 62 |        orient="auto"
 63 |        refY="0"
 64 |        refX="0"
 65 |        id="Arrow1Lend-0"
 66 |        style="overflow:visible">
 67 |       <path
 68 |          inkscape:connector-curvature="0"
 69 |          id="path3957-1"
 70 |          d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
 71 |          style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none"
 72 |          transform="matrix(-0.8,0,0,-0.8,-10,0)" />
 73 |     </marker>
 74 |     <marker
 75 |        inkscape:stockid="Arrow1Lend"
 76 |        orient="auto"
 77 |        refY="0"
 78 |        refX="0"
 79 |        id="marker4630"
 80 |        style="overflow:visible">
 81 |       <path
 82 |          inkscape:connector-curvature="0"
 83 |          id="path4632"
 84 |          d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
 85 |          style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none"
 86 |          transform="matrix(-0.8,0,0,-0.8,-10,0)" />
 87 |     </marker>
 88 |   </defs>
 89 |   <sodipodi:namedview
 90 |      id="base"
 91 |      pagecolor="#ffffff"
 92 |      bordercolor="#666666"
 93 |      borderopacity="1.0"
 94 |      inkscape:pageopacity="0.0"
 95 |      inkscape:pageshadow="2"
 96 |      inkscape:zoom="1.1128612"
 97 |      inkscape:cx="482.75647"
 98 |      inkscape:cy="470.93358"
 99 |      inkscape:document-units="px"
100 |      inkscape:current-layer="layer1"
101 |      showgrid="false"
102 |      showguides="true"
103 |      inkscape:guide-bbox="true"
104 |      inkscape:window-width="1920"
105 |      inkscape:window-height="1023"
106 |      inkscape:window-x="0"
107 |      inkscape:window-y="26"
108 |      inkscape:window-maximized="1" />
109 |   <metadata
110 |      id="metadata7">
111 |     <rdf:RDF>
112 |       <cc:Work
113 |          rdf:about="">
114 |         <dc:format>image/svg+xml</dc:format>
115 |         <dc:type
116 |            rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
117 |         <dc:title />
118 |       </cc:Work>
119 |     </rdf:RDF>
120 |   </metadata>
121 |   <g
122 |      inkscape:label="Layer 1"
123 |      inkscape:groupmode="layer"
124 |      id="layer1"
125 |      transform="translate(0,-308.2677)">
126 |     <rect
127 |        style="fill:#ffffff;stroke:#ffffff;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none"
128 |        id="rect4709"
129 |        width="1036.0681"
130 |        height="476.24988"
131 |        x="3.5943387"
132 |        y="38.705528"
133 |        transform="translate(0,308.2677)" />
134 |     <rect
135 |        style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none"
136 |        id="rect2985"
137 |        width="184.6295"
138 |        height="188.2908"
139 |        x="37.519623"
140 |        y="449.09991"
141 |        ry="7.7379818" />
142 |     <rect
143 |        style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none"
144 |        id="rect2987"
145 |        width="39.567055"
146 |        height="27.573088"
147 |        x="76.403419"
148 |        y="502.64304"
149 |        ry="0" />
150 |     <text
151 |        xml:space="preserve"
152 |        style="font-size:14px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
153 |        x="61.9645"
154 |        y="419.76434"
155 |        id="text2989"
156 |        sodipodi:linespacing="125%"><tspan
157 |          sodipodi:role="line"
158 |          id="tspan2991"
159 |          x="61.9645"
160 |          y="419.76434"
161 |          style="font-size:22px">Application</tspan></text>
162 |     <rect
163 |        style="fill:none;stroke:#000000;stroke-width:0.97812361;stroke-miterlimit:4;stroke-dasharray:none"
164 |        id="rect2995"
165 |        width="187.60904"
166 |        height="190.03397"
167 |        x="405.59735"
168 |        y="453.27908"
169 |        ry="10.721515" />
170 |     <text
171 |        xml:space="preserve"
172 |        style="font-size:22px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
173 |        x="483.44183"
174 |        y="421.71405"
175 |        id="text2997"
176 |        sodipodi:linespacing="125%"><tspan
177 |          sodipodi:role="line"
178 |          id="tspan2999"
179 |          x="483.44183"
180 |          y="421.71405">API</tspan></text>
181 |     <text
182 |        xml:space="preserve"
183 |        style="font-size:14px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
184 |        x="310.42389"
185 |        y="566.68384"
186 |        id="text4583"
187 |        sodipodi:linespacing="125%"><tspan
188 |          sodipodi:role="line"
189 |          id="tspan4585"
190 |          x="310.42389"
191 |          y="566.68384"
192 |          style="font-size:12px">to_resource()</tspan><tspan
193 |          sodipodi:role="line"
194 |          x="310.42389"
195 |          y="581.68384"
196 |          id="tspan4671"
197 |          style="font-size:12px">from_resource()</tspan></text>
198 |     <text
199 |        xml:space="preserve"
200 |        style="font-size:18px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
201 |        x="422.30914"
202 |        y="689.50037"
203 |        id="text4587"
204 |        sodipodi:linespacing="125%"><tspan
205 |          sodipodi:role="line"
206 |          id="tspan4589"
207 |          x="422.30914"
208 |          y="689.50037"
209 |          style="font-style:italic;-inkscape-font-specification:Sans Italic">Resource Model</tspan></text>
210 |     <text
211 |        xml:space="preserve"
212 |        style="font-size:18px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
213 |        x="121.07899"
214 |        y="674.34192"
215 |        id="text4591"
216 |        sodipodi:linespacing="125%"><tspan
217 |          sodipodi:role="line"
218 |          id="tspan4593"
219 |          x="121.07899"
220 |          y="674.34192"
221 |          style="font-style:italic;text-align:center;text-anchor:middle;-inkscape-font-specification:Sans Italic">Application</tspan><tspan
222 |          sodipodi:role="line"
223 |          x="121.07899"
224 |          y="696.84192"
225 |          style="font-style:italic;text-align:center;text-anchor:middle;-inkscape-font-specification:Sans Italic"
226 |          id="tspan3060">Data Model</tspan></text>
227 |     <rect
228 |        style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none"
229 |        id="rect4595"
230 |        width="199.00005"
231 |        height="184.85791"
232 |        x="800.16266"
233 |        y="457.38232"
234 |        ry="10.721515" />
235 |     <text
236 |        xml:space="preserve"
237 |        style="font-size:22px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
238 |        x="861.53571"
239 |        y="421.89667"
240 |        id="text2997-4"
241 |        sodipodi:linespacing="125%"><tspan
242 |          sodipodi:role="line"
243 |          id="tspan2999-4"
244 |          x="861.53571"
245 |          y="421.89667">Client</tspan></text>
246 |     <path
247 |        style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow1Lend)"
248 |        d="m 633.10001,524.19842 125.25891,0"
249 |        id="path3001-5"
250 |        inkscape:connector-curvature="0" />
251 |     <path
252 |        style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow1Lend)"
253 |        d="m 757.34877,536.46239 -124.24876,0"
254 |        id="path4399-2"
255 |        inkscape:connector-curvature="0" />
256 |     <text
257 |        xml:space="preserve"
258 |        style="font-size:14px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
259 |        x="694.98492"
260 |        y="282.45477"
261 |        id="text4653"
262 |        sodipodi:linespacing="125%"
263 |        transform="translate(0,308.2677)"><tspan
264 |          sodipodi:role="line"
265 |          id="tspan4655"
266 |          x="694.98492"
267 |          y="282.45477" /></text>
268 |     <flowRoot
269 |        xml:space="preserve"
270 |        id="flowRoot4663"
271 |        style="fill:black;stroke:none;stroke-opacity:1;stroke-width:1px;stroke-linejoin:miter;stroke-linecap:butt;fill-opacity:1;font-family:Sans;font-style:normal;font-weight:normal;font-size:14px;line-height:125%;letter-spacing:0px;word-spacing:0px;-inkscape-font-specification:Sans"><flowRegion
272 |          id="flowRegion4665"><rect
273 |            id="rect4667"
274 |            width="293.83719"
275 |            height="390.88434"
276 |            x="402.56592"
277 |            y="43.198444" /></flowRegion><flowPara
278 |          id="flowPara4669" /></flowRoot>    <path
279 |        style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:none;marker-end:url(#marker4630)"
280 |        d="m 246.82069,521.29864 123.45787,0"
281 |        id="path4673"
282 |        inkscape:connector-curvature="0" />
283 |     <path
284 |        style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#marker4630)"
285 |        d="m 367.5831,533.27034 -120.76241,0"
286 |        id="path5047"
287 |        inkscape:connector-curvature="0" />
288 |     <text
289 |        xml:space="preserve"
290 |        style="font-size:14px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
291 |        x="390.88434"
292 |        y="220.21962"
293 |        id="text5235"
294 |        sodipodi:linespacing="125%"
295 |        transform="translate(0,308.2677)"><tspan
296 |          sodipodi:role="line"
297 |          id="tspan5237"
298 |          x="390.88434"
299 |          y="220.21962" /></text>
300 |     <text
301 |        xml:space="preserve"
302 |        style="font-size:14px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
303 |        x="438.3631"
304 |        y="491.64536"
305 |        id="text5239"
306 |        sodipodi:linespacing="125%"><tspan
307 |          sodipodi:role="line"
308 |          id="tspan5241"
309 |          x="438.3631"
310 |          y="491.64536">/entrypoint</tspan><tspan
311 |          sodipodi:role="line"
312 |          x="438.3631"
313 |          y="509.14536"
314 |          id="tspan5259">    /collection1</tspan><tspan
315 |          sodipodi:role="line"
316 |          x="438.3631"
317 |          y="526.64539"
318 |          id="tspan5261">        /resource1</tspan><tspan
319 |          sodipodi:role="line"
320 |          x="438.3631"
321 |          y="544.14539"
322 |          id="tspan5263">        /resource2</tspan><tspan
323 |          sodipodi:role="line"
324 |          x="438.3631"
325 |          y="561.64539"
326 |          id="tspan5267">    /collection2</tspan><tspan
327 |          sodipodi:role="line"
328 |          x="438.3631"
329 |          y="579.14539"
330 |          id="tspan5271">        /resource1</tspan><tspan
331 |          sodipodi:role="line"
332 |          x="438.3631"
333 |          y="596.64539"
334 |          id="tspan5245">        /resrouce2</tspan><tspan
335 |          sodipodi:role="line"
336 |          x="438.3631"
337 |          y="614.14539"
338 |          id="tspan5297">    ....</tspan></text>
339 |     <text
340 |        xml:space="preserve"
341 |        style="font-size:14px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
342 |        x="697.70532"
343 |        y="553.30017"
344 |        id="text4657"
345 |        sodipodi:linespacing="125%"><tspan
346 |          sodipodi:role="line"
347 |          id="tspan4659"
348 |          x="697.70532"
349 |          y="553.30017" /><tspan
350 |          sodipodi:role="line"
351 |          x="697.70532"
352 |          y="568.8067"
353 |          style="font-size:12px;text-align:center;text-anchor:middle"
354 |          id="tspan5299">application/x-collection</tspan><tspan
355 |          sodipodi:role="line"
356 |          x="697.70532"
357 |          y="583.8067"
358 |          style="font-size:12px;text-align:center;text-anchor:middle"
359 |          id="tspan3064">application/x-resource</tspan></text>
360 |     <flowRoot
361 |        xml:space="preserve"
362 |        id="flowRoot5303"
363 |        style="fill:black;stroke:none;stroke-opacity:1;stroke-width:1px;stroke-linejoin:miter;stroke-linecap:butt;fill-opacity:1;font-family:Sans;font-style:normal;font-weight:normal;font-size:14px;line-height:125%;letter-spacing:0px;word-spacing:0px;-inkscape-font-specification:Sans"><flowRegion
364 |          id="flowRegion5305"><rect
365 |            id="rect5307"
366 |            width="128.4976"
367 |            height="28.754709"
368 |            x="840.17664"
369 |            y="241.78566" /></flowRegion><flowPara
370 |          id="flowPara5309" /></flowRoot>    <rect
371 |        style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none"
372 |        id="rect5311"
373 |        width="112.32308"
374 |        height="25.16037"
375 |        x="841.65546"
376 |        y="575.21368"
377 |        ry="0" />
378 |     <text
379 |        xml:space="preserve"
380 |        style="font-size:14px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
381 |        x="856.03278"
382 |        y="591.38824"
383 |        id="text5313"
384 |        sodipodi:linespacing="125%"><tspan
385 |          sodipodi:role="line"
386 |          id="tspan5315"
387 |          x="856.03278"
388 |          y="591.38824">HTTP Library</tspan></text>
389 |     <flowRoot
390 |        xml:space="preserve"
391 |        id="flowRoot5317"
392 |        style="fill:black;stroke:none;stroke-opacity:1;stroke-width:1px;stroke-linejoin:miter;stroke-linecap:butt;fill-opacity:1;font-family:Sans;font-style:normal;font-weight:normal;font-size:14px;line-height:125%;letter-spacing:0px;word-spacing:0px;-inkscape-font-specification:Sans"><flowRegion
393 |          id="flowRegion5319"><rect
394 |            id="rect5321"
395 |            width="113.22166"
396 |            height="40.43631"
397 |            x="850.95966"
398 |            y="225.61113" /></flowRegion><flowPara
399 |          id="flowPara5323" /></flowRoot>    <rect
400 |        ry="0"
401 |        y="529.43762"
402 |        x="841.65546"
403 |        height="45.429256"
404 |        width="112.32308"
405 |        id="rect5325"
406 |        style="fill:none;stroke:#000000;stroke-width:1.34372163;stroke-miterlimit:4;stroke-dasharray:none" />
407 |     <text
408 |        xml:space="preserve"
409 |        style="font-size:14px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
410 |        x="898.57941"
411 |        y="547.56042"
412 |        id="text5327"
413 |        sodipodi:linespacing="125%"><tspan
414 |          sodipodi:role="line"
415 |          id="tspan5329"
416 |          x="898.57941"
417 |          y="547.56042"
418 |          style="text-align:center;text-anchor:middle">REST Library</tspan><tspan
419 |          sodipodi:role="line"
420 |          x="898.57941"
421 |          y="565.06042"
422 |          id="tspan5331"
423 |          style="text-align:center;text-anchor:middle">(optional)</tspan></text>
424 |     <rect
425 |        ry="0"
426 |        y="504.11224"
427 |        x="841.65546"
428 |        height="25.16037"
429 |        width="112.32308"
430 |        id="rect5333"
431 |        style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none" />
432 |     <text
433 |        xml:space="preserve"
434 |        style="font-size:14px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
435 |        x="863.67078"
436 |        y="519.05219"
437 |        id="text5335"
438 |        sodipodi:linespacing="125%"><tspan
439 |          sodipodi:role="line"
440 |          id="tspan5337"
441 |          x="863.67078"
442 |          y="519.05219">Client App</tspan></text>
443 |     <rect
444 |        style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none"
445 |        id="rect5339"
446 |        width="564.4278"
447 |        height="22.464617"
448 |        x="35.044804"
449 |        y="719.88586" />
450 |     <text
451 |        xml:space="preserve"
452 |        style="font-size:14px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
453 |        x="262.38672"
454 |        y="735.36462"
455 |        id="text5341"
456 |        sodipodi:linespacing="125%"><tspan
457 |          sodipodi:role="line"
458 |          id="tspan5343"
459 |          x="262.38672"
460 |          y="735.36462">Server</tspan></text>
461 |     <rect
462 |        y="719.88586"
463 |        x="802.38147"
464 |        height="22.464617"
465 |        width="202.74103"
466 |        id="rect5347"
467 |        style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none" />
468 |     <text
469 |        xml:space="preserve"
470 |        style="font-size:14px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
471 |        x="880.9903"
472 |        y="736.66882"
473 |        id="text5349"
474 |        sodipodi:linespacing="125%"><tspan
475 |          sodipodi:role="line"
476 |          id="tspan5351"
477 |          x="880.9903"
478 |          y="736.66882">Client</tspan></text>
479 |     <rect
480 |        style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none"
481 |        id="rect2987-2"
482 |        width="39.567055"
483 |        height="27.573088"
484 |        x="142.28012"
485 |        y="503.62766"
486 |        ry="0" />
487 |     <rect
488 |        ry="0"
489 |        y="549.62769"
490 |        x="112.28012"
491 |        height="27.573088"
492 |        width="39.567055"
493 |        id="rect3869"
494 |        style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none" />
495 |     <path
496 |        style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow1Mend)"
497 |        d="m 91.07545,530.48733 0,30.55188 20.66745,0"
498 |        id="path3871"
499 |        inkscape:connector-curvature="0" />
500 |     <path
501 |        style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow1Mend)"
502 |        d="m 116.23582,516.3128 25.16037,0"
503 |        id="path4509"
504 |        inkscape:connector-curvature="0" />
505 |     <text
506 |        xml:space="preserve"
507 |        style="font-size:14px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
508 |        x="310.14996"
509 |        y="410.16425"
510 |        id="text4699"
511 |        sodipodi:linespacing="125%"><tspan
512 |          sodipodi:role="line"
513 |          id="tspan4701"
514 |          x="310.14996"
515 |          y="410.16425"
516 |          style="font-style:italic;text-align:center;text-anchor:middle;-inkscape-font-specification:Sans Italic">Application</tspan><tspan
517 |          sodipodi:role="line"
518 |          x="310.14996"
519 |          y="427.66425"
520 |          id="tspan4703"
521 |          style="font-style:italic;text-align:center;text-anchor:middle;-inkscape-font-specification:Sans Italic">Interface</tspan></text>
522 |     <text
523 |        xml:space="preserve"
524 |        style="font-size:14px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
525 |        x="681.9668"
526 |        y="418.79803"
527 |        id="text4705"
528 |        sodipodi:linespacing="125%"><tspan
529 |          sodipodi:role="line"
530 |          id="tspan4707"
531 |          x="681.9668"
532 |          y="418.79803"
533 |          style="font-style:italic;-inkscape-font-specification:Sans Italic">HTTP</tspan></text>
534 |   </g>
535 | </svg>
536 | 


--------------------------------------------------------------------------------
/index.rst:
--------------------------------------------------------------------------------
 1 | .. RESTful API Design master file, created by sphinx-quickstart on Mon
 2 |    Jul 25 09:21:34 2011.  You can adapt this file completely to your
 3 |    liking, but it should at least contain the root `toctree` directive.
 4 | 
 5 | =======================================================================
 6 |                    Thoughts on RESTful API Design
 7 | =======================================================================
 8 | Lessons learnt from designing the Red Hat Enterprise Virtualization API
 9 | -----------------------------------------------------------------------
10 | 
11 | Author: Geert Jansen <gjansen@redhat.com>
12 | 
13 | Date: November 15th, 2012
14 | 
15 | This work is licensed under a `Creative Commons Attribution 3.0 Unported
16 | License <http://creativecommons.org/licenses/by/3.0/>`_.
17 | 
18 | The source of this document can be found `on github
19 | <http://github.com/geertj/restful-api-design>`_.
20 | 
21 | .. toctree::
22 |    :maxdepth: 2
23 | 
24 |    intro
25 |    scope
26 |    resources
27 |    urls
28 |    methods
29 |    relationships
30 |    forms
31 |    misc
32 | 


--------------------------------------------------------------------------------
/intro.rst:
--------------------------------------------------------------------------------
 1 | ============
 2 | Introduction
 3 | ============
 4 | 
 5 | This essay is an attempt to put down my thoughts on how to design a
 6 | real-world yet beautiful RESTful API. It draws from the experience I have
 7 | gained being involved in the design of the `RESTful API
 8 | <http://bitbucket.org/geertj/rhevm-api/wiki/Home>`_ for Red Hat's Enterprise
 9 | Virtualization product, `twice <http://fedorahosted.org/rhevm-api/>`_.  During
10 | the design phase of the API we had to solve many of the real-world problems
11 | described above, but we weren't willing to add non-RESTful or "RPC-like"
12 | interfaces to our API too easily.
13 | 
14 | In my definition, a real-world RESTful API is an API that provides answers to
15 | questions that you won't find in introductory texts, but that inevitably
16 | surface in the real world, such as whether or not resources should be
17 | described formally, how to create useful and automatic command-line
18 | interfaces, how to do polling, asynchronous and other non-standard types of
19 | requests, and how to deal with operations that have no good RESTful mapping.
20 | 
21 | A beautiful RESTful API on the other hand is one that does not deviate from
22 | the principles of RESTful architecture style too easily. One important design
23 | element for example that is not always addressed is the possibility for
24 | complete auto-discovery by the API user, so that the API can be used by a
25 | human with a web browser, without any reference to external documentation. I
26 | will discuss this issue in detail in :doc:`forms`.
27 | 
28 | This essay does not attempt to explain the basics about REST, as there are
29 | many other texts about that. For a good description of REST, I would recommend
30 | reading at least `the Atom Publishing Protocol
31 | <http://tools.ietf.org/html/rfc5023>`_ and `this blog post
32 | <http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven>`_ by
33 | Roy Fielding.
34 | 
35 | While the views exposed in this essay are my own, they are heavily based on
36 | the public discussion on the `rhevm-api mailing list
37 | <https://fedorahosted.org/mailman/listinfo/rhevm-api>`_.  My thanks goes to
38 | all people who have contributed and are still contributing to it, including
39 | Mark McLoughlin, Michael Pasternak, Ori Liel, Sander Hoentjen, Ewoud Kohl van
40 | Wijngaarden, Tomas V.V. Cox and everybody else I forgot.
41 | 


--------------------------------------------------------------------------------
/methods.rst:
--------------------------------------------------------------------------------
  1 | =======
  2 | Methods
  3 | =======
  4 | 
  5 | Standard Methods
  6 | ================
  7 | 
  8 | We already discussed that resources are the fundamental concept in a RESTful
  9 | API, and that each resource has its own unique URL. Methods can be executed on
 10 | resources via their URL.
 11 | 
 12 | The table below lists the standard methods that have a well-defined meaning for
 13 | all resources and collections.
 14 | 
 15 | =======  ==========  ==================================================
 16 | Method     Scope                         Semantics
 17 | =======  ==========  ==================================================
 18 | GET      collection  Retrieve all resources in a collection
 19 | GET      resource    Retrieve a single resource
 20 | HEAD     collection  Retrieve all resources in a collection (header only)
 21 | HEAD     resource    Retrieve a single resource (header only)
 22 | POST     collection  Create a new resource in a collection
 23 | PUT      resource    Update a resource
 24 | PATCH    resource    Update a resource
 25 | DELETE   resource    Delete a resource
 26 | OPTIONS  any         Return available HTTP methods and other options
 27 | =======  ==========  ==================================================
 28 | 
 29 | Normally, not all resources and collections implement all methods. There are
 30 | two ways to find out which methods are accepted by a resource or collection.
 31 | 
 32 | 1. Use the OPTIONS method on the URL, and look at the "Allow" header that is
 33 |    returned. This header contains a comma-separated list of methods are are
 34 |    supported for the resource or collection.
 35 | 2. Just issue the method you want to issue, but be prepared for a "405 Method
 36 |    Not Allowed" response that indicates the method is not accepted for this
 37 |    resource or collection.
 38 | 
 39 | 
 40 | Actions
 41 | =======
 42 | 
 43 | Sometimes, it is required to expose an operation in the API that inherently is
 44 | non RESTful. One example of such an operation is where you want to introduce a
 45 | state change for a resource, but there are multiple ways in which the same
 46 | final state can be achieved, and those ways actually differ in a significant
 47 | but non-observable side-effect. Some may say such transitions are bad API
 48 | design, but not having to model all state can greatly simplify an API. A great
 49 | example of this is the difference between a "power off" and a "shutdown" of a
 50 | virtual machine. Both will lead to a vm resource in the "DOWN" state.
 51 | However, these operations are quite different.
 52 | 
 53 | As a solution to such non-RESTful operations, an "actions" sub-collection can
 54 | be used on a resource. Actions are basically RPC-like messages to a resource
 55 | to perform a certain operation. The "actions" sub-collection can be seen as a
 56 | command queue to which new action can be POSTed, that are then executed by the
 57 | API. Each action resource that is POSTed, should have a "type" attribute that
 58 | indicates the type of action to be performed, and can have arbitrary other
 59 | attributes that parameterize the operation.
 60 | 
 61 | It should be noted that actions should only be used as an exception, when
 62 | there's a good reason that an operation cannot be mapped to one of the
 63 | standard RESTful methods. If an API has too many actions, then that's an
 64 | indication that either it was designed with an RPC viewpoint rather than using
 65 | RESTful principles, or that the API in question is naturally a better fit for
 66 | an RPC type model.
 67 | 
 68 | 
 69 | PATCH vs PUT
 70 | ============
 71 | 
 72 | The HTTP RFC specifies that PUT must take a full new resource representation as
 73 | the request entity. This means that if for example only certain attributes are
 74 | provided, those should be removed (i.e. set to null).
 75 | 
 76 | An additional method called PATCH `has been proposed recently
 77 | <http://tools.ietf.org/html/rfc5789>`_. The semantics of this call are like PUT
 78 | inthat it updates a resource, but unlike PUT, it applies a delta rather than
 79 | replacing the entire resource. At the time of writing, PATCH was still a
 80 | proposed standard waiting final approval.
 81 | 
 82 | For simple resource representations, the difference is often not important, and
 83 | many APIs simply implement PUT as a synonym for PATCH. This usually doesn't
 84 | give any problems because it is not very common that you need to set an
 85 | attribute to null, and if you need to, you can always explicitly include it.
 86 | 
 87 | However for more complex representations, especially including lists, it
 88 | becomes very important to be able to express accurately the changes you want to
 89 | make. Therefore, it is my recommendation now to both provide PATCH and PUT, and
 90 | make PATCH do an relative update and have PUT replace the entire resource.
 91 | 
 92 | It is important to realize that the request entity to PATCH is of a different
 93 | content-type than the entity that it is modifying. Instead of being a full
 94 | resource, it is a resource that describes modifications to be made to a
 95 | resource. For a JSON data model, which is what this essay is advocating, I
 96 | believe that there are two sensible ways to define the patch format.
 97 | 
 98 | 1. An informal approach where you accept a dict with a partial representation
 99 |    of the object. Only attributes that are present are updated. Attributes that
100 |    are not present are left alone. This approach is simple, but it has the
101 |    drawback that if the resource has a complex internal structure e.g.
102 |    containing a big list of dicts, then that entire list of dicts need to be
103 |    given in the entity. Effectively PATCH becomes similar to PUT again.
104 | 
105 | 2. A more formal approach would be to accept a list of modifications. Each
106 |    modification can be a dict specifying the JSON path of the node to modify,
107 |    the modification ('add', 'remove', 'change') and the new value.
108 | 
109 | 
110 | Link Headers
111 | ============
112 | 
113 | An `Internet draft
114 | <http://tools.ietf.org/html/draft-nottingham-http-link-header-10>`_ exists
115 | defining the "Link:" header type.  This header takes the "link" attributes of
116 | the response entity, and formats them as an HTTP header. It is argued that the
117 | Link header is useful because it allows a client to quickly get links from a
118 | response without having to parse the response entity, or even without
119 | retrieving the response entity at all using the HEAD HTTP method.
120 | 
121 | In my view, the usefulness of this feature is dubious. First of all, it can
122 | increase response sizes quite significantly. Second, it can only be used when
123 | a resource is being returned; it does not make sense to be used with
124 | collections. Because I have not yet seen any good use of this header in the
125 | context of a RESTful API, I recommend not to implement Link headers.
126 | 
127 | 
128 | Asynchronous Requests
129 | =====================
130 | 
131 | Sometimes an action takes too long to be completed in the context of a single
132 | HTTP request. In that case, a "202 Accepted" status can be returned to the
133 | client. Such a response should only be returned for POST, PUT, PATCH or DELETE.
134 | 
135 | The response entity of a 202 Accepted response should be a regular resource
136 | with only the information filled in that was available at the time the request
137 | was accepted. The resource should contain a "link" attribute that points to a
138 | status monitor that can be polled to get updated status information.
139 | 
140 | When polling the status monitor, it should return a "response" object with
141 | information on the current status of the asynchronous request. If the request
142 | is still in progress, such a response could look like this (in YAML)::
143 | 
144 |   !response
145 |   status: 202 Accepted
146 |   progress: 50%
147 | 
148 | If the call has finished, the response should include the same headers and
149 | response body had the request been fulfilled synchronously::
150 | 
151 |   !response
152 |   status: 201 Created
153 |   headers:
154 |    - name: content-type
155 |      value: applicaton/x-resource+yaml
156 |   response: !!str
157 |     Response goes here
158 | 
159 | After the response has been retrieved once with a status that is not equal to
160 | "202 Accepted", the API code may garbage collect it and therefore clients
161 | should not assume it will continue to be available.
162 | 
163 | A client may request the server to modify its asynchronous behavior with the
164 | following "Expect" headers:
165 | 
166 | * "Expect: 200-ok/201-created/204-no-content" disables all asynchronous
167 |   functionality. The server may return a "417 Expectation Failed" 
168 |   if it is not willing to wait for an operation to complete.
169 | * "Expect: 202-accepted" explicitly request an asynchronous response. The
170 |   server may return a "417 Expectation Failed" if it is not willing to perform
171 |   the request asynchronously.
172 | 
173 | If no expectation is provided, client must be prepared to accept a 202
174 | Accepted status for any request other than GET.
175 | 
176 | 
177 | Ranges / Pagination
178 | ===================
179 | 
180 | When collections contain many resources, it is quite a common
181 | requirement for a client to retrieve only a subset of the available resources.
182 | This can be implemented using the Range header with a "resource" range unit:
183 | 
184 | .. code-block:: none
185 | 
186 |   GET /api/collection
187 |   Range: resources=100-199
188 | 
189 | The above example would return resources 100 through 199 (inclusive).
190 | 
191 | Note that it is the responsibility of the API implementer to ensure a proper
192 | and preferably meaningful ordering can be guaranteed for the resources.
193 | 
194 | Servers should provide an "Accept-Ranges: resource" header to indicate to a
195 | client that they support resource-based range queries. This header should be
196 | provided in an OPTIONS response:
197 | 
198 | .. code-block:: none
199 | 
200 |   OPTIONS /api/collection HTTP/1.1
201 | 
202 |   HTTP/1.1 200 OK
203 |   Accept-Ranges: resources
204 | 
205 | 
206 | Notifications
207 | =============
208 | 
209 | Another common requirement is where a client wants to be notified immediately
210 | when some kind of event happens.
211 | 
212 | Ideally, such a notification would be implemented using a call-out from the
213 | server to the client. However, there is no good portable standard to do this
214 | over HTTP, and it also breaks with network address translation and HTTP
215 | proxies.  A second approach called busy-loop polling is horribly inefficient.
216 | 
217 | In my view, the best approach is what is is called "long polling". In long
218 | polling, the client will retrieve a URL but the server will not generate a
219 | response yet. The client will wait for a configurable amount of time, until it
220 | will close the connection and reconnect. If the server becomes aware of an
221 | event that requires notification of clients, it can provide that event
222 | immediately to clients that are currently waiting.
223 | 
224 | Long polling should be disabled by default, and can be enabled by a client
225 | using an Expect header. For example, a client could long poll for new
226 | resources in a collection using a combination of long-polling and a
227 | resource-based range query:
228 | 
229 | .. code-block:: none
230 | 
231 |   GET /api/collection
232 |   Range: 100-
233 |   Expect: nonempty-response
234 | 
235 | In this case, resource "100" would be the last resource that was read, and the
236 | call is requesting the API to return at least one resource with an ID > 100.
237 | 
238 | Server implementers need to decide whether they want to implement long polling
239 | using one thread per waiting client, or one thread that uses multiplexed IO to
240 | wait for all clients. This is a trade-off to be made between ease of
241 | implementation and scalability (that said, threads are pretty cheap on modern
242 | operating systems).
243 | 


--------------------------------------------------------------------------------
/misc.rst:
--------------------------------------------------------------------------------
 1 | ====================
 2 | Miscellaneous Topics
 3 | ====================
 4 | 
 5 | Offline Help
 6 | ============
 7 | 
 8 | A requirement that sometimes comes up is that to have an offline description
 9 | of the API that can be used to generate offline help for a command-line
10 | interface (CLI) for that API. When connected to an API, all this information
11 | is of course available because of the self-descriptive nature of a RESTful
12 | API. But the request is to have that information offline as well, so that CLI
13 | users can get help without have to connect first.
14 | 
15 | In my view it is a bad idea to offer this offline help. It introduces a
16 | tight coupling between a client and a server, which will break the RESTful
17 | model. A server cannot be independently upgraded anymore from a client, and
18 | clients become tied to a specific server version. Also I doubt the usefulness
19 | of this feature as having to connect first to get help does not seem like a
20 | big issue to me.
21 | 
22 | That said, it is relatively straightforward to define a way that such an offline
23 | description can be facilitated.
24 | 
25 | One server-side change is required for this. For each collection, the API
26 | should implement a placeholder resource with a special ID (let's say "_", but
27 | it doesn't matter as long as it cannot be a valid ID), and some fake data.
28 | When a special HTTP Expect header is set, only this placeholder resource is
29 | returned when querying a collection.
30 | 
31 | Having the placeholder resources in place for every collection, the following
32 | procedure can be used by the client to retrieve all relevant metadata:
33 | 
34 | 1. Retrieve the entry point of the API and store it in memory as a resource.
35 | 2. For every hyperlink in the entry point, fetch the target, and store it
36 |    under the "target" property under the link object, recursively. When
37 |    collections are retrieved, the special Expect header must be set.
38 | 3. For every hyperlink in the entry point, execute an OPTIONS call on the
39 |    target, and store the resulting headers under the "options" property of the
40 |    link object, recursively.
41 | 4. Serialize the resulting object to a file.
42 | 
43 | The result of this is basically a recursive dump of the "GET"-able part of an
44 | API with one placeholder resource in every collection. It will contain all
45 | metadata including forms, options, available resource types and collections,
46 | in a format that is very similar to the real on-line data. It can be used as
47 | an off-line store to generate any help that you would be able to generate
48 | online as well.
49 | 
50 | An API can store a version number on its entry point, so that clients can see
51 | when their offline cached copy expired and can therefore generate a new one.
52 | 


--------------------------------------------------------------------------------
/relationships.rst:
--------------------------------------------------------------------------------
  1 | =============
  2 | Relationships
  3 | =============
  4 | 
  5 | As we have seen in :doc:`resources`, the resource is the fundamental unit in
  6 | RESTful API design. Resources model objects from the application data model.
  7 | 
  8 | Resources do not exist in isolation, but have relationships to other
  9 | resources. Sometimes these relationships exist between the mapped objects in
 10 | the application data model as well, sometimes they are specific to the RESTful
 11 | resources.
 12 | 
 13 | One of the principles of the RESTful architecture style is that these
 14 | relationships are expressed by hyperlinks to the representation of a resource.
 15 | 
 16 | In our resource model, we interpret any object with an "href" attribute as a
 17 | hyperlink. The value of the href attribute contains an absolute URL that can
 18 | be retrieved with GET. Using GET on a such a URL is guaranteed to be
 19 | side-effect free.
 20 | 
 21 | Two types of hyperlinks are normally used:
 22 | 
 23 | 1. Using "link" objects. This is a special object of type "link" with
 24 |    "href" and a "rel" attributes. The "rel" attribute value identifies the
 25 |    semantics of the relationship. The link object is borrowed from
 26 |    `HTML <http://www.w3.org/TR/html4/struct/links.html>`_.
 27 | 2. Using any object with a "href" attribute. The object type defines the
 28 |    semantics of the relationship. I'll call these "object links," not to be
 29 |    confused with the "link objects" above.
 30 | 
 31 | Below is an example of a virtual machine representation in YAML that
 32 | illustrates the two different ways in which a relationship can be expressed::
 33 | 
 34 |   !vm
 35 |   id: 123
 36 |   href: /api/vms/123
 37 |   link:
 38 |     rel: collection/nics
 39 |     href: /api/vms/123/nics
 40 |   cluster:
 41 |     href: /api/clusters/456
 42 | 
 43 | The "link" object is used with rel="collection/nics" to refer to a
 44 | sub-collection to the VM holding the virtual network interfaces. The cluster
 45 | link instead points to the cluster containing this VM by means of a "cluster"
 46 | object.
 47 | 
 48 | Note that the VM itself has a href attribute as well. This is called a "self"
 49 | link, and it is a convention for a resource to provide such a link. That way,
 50 | the object can later be easily re-retrieved or updated without keeping
 51 | external state.
 52 | 
 53 | There are no absolute rules when to use link objects, and when not. That said,
 54 | we have been using the rules below in the rhevm-api project with good success.
 55 | They seem to be a good trade-off between compactness (favoring object links)
 56 | and the ability to understand links without understanding the specific
 57 | resource model (favoring link objects).
 58 | 
 59 | * Link objects are used to express structural relationships in the API. So for
 60 |   example, the top-level collections, singleton resources and sub-collections
 61 |   (including actions) are all referenced using link objects.
 62 | * Object links are used to express semantic relationships from the
 63 |   application data model. In the example above, the vm to cluster link comes
 64 |   directly from the application data model and is therefore modeled as a link.
 65 | 
 66 | Note however that sub-collections can express both a semantic relationship,
 67 | as well as a structural relationship. See for example the "collection/nics"
 68 | sub-collection to a VM in the example above. In such a case, our convention
 69 | has been to use link objects.
 70 | 
 71 | 
 72 | Standard Structural Relationships
 73 | ---------------------------------
 74 | 
 75 | It makes sense to define a few standard structural relationship names that can
 76 | be relevant to many different APIs. In this way, client authors know what to
 77 | expect and can write to some extent portable clients that work with multiple
 78 | APIs. The table below contains a few of these relationship names.
 79 | 
 80 | =================  =====================================
 81 | Relationship                     Semantics
 82 | =================  =====================================
 83 | collection/{name}  Link to a related collection {name}.
 84 | resource/{name}    Link to a related resource {name}.
 85 | form/{name}        Link to a related form {name}.
 86 | =================  =====================================
 87 | 
 88 | Here, {name} is replaced with a term that has meaning for the specific API.
 89 | For example, a collection of virtual machines could be linked from the entry
 90 | point of a virtualization API using rel="collection/vms".
 91 | 
 92 | 
 93 | Modeling Semantic Relationships
 94 | -------------------------------
 95 | 
 96 | Semantic relationships can be modeled either by an object link, or by a
 97 | sub-collection. I believe that choosing the right way to represent a
 98 | sub-collection is important to get a consistent API experience for the client.
 99 | I would advocate using the following rules:
100 | 
101 | 1. In case of a 1:N relationship, where the target object is **existentially
102 |    dependent** on the source object, I'd recommend to use a sub-collection.
103 |    By "existentially dependent" I mean that a target object cannot exist
104 |    without its source. In database parlance, this would be a FOREIGN KEY
105 |    relationship with an ON DELETE CASCADE. An example of such a relationship
106 |    are the NICs that are associated with a VM.
107 | 2. In case of a 1:N relationship, where there is data that is associated with
108 |    the link, I'd recommend to use a sub-collection. Note that we are talking
109 |    about data here that is neither part of the source object, nor the target
110 |    object.  The resources in the sub-collection can hold the extra data. In
111 |    this case, the data in the sub-resource would therefore be a merge of the
112 |    data from the mapped object from the application data model, and link data.
113 | 3. In case of any other 1:N relationship, I'd recommend to use an object link.
114 | 4. In case of a N:M relationship, I'd recommend to use a sub-collection.
115 |    The sub-collection can be defined initially to support the lookup direction
116 |    that you most often need to follow. If you need to query both sides of the
117 |    relationship often, then two sub-collections can be defined, one on each
118 |    linked object.
119 | 


--------------------------------------------------------------------------------
/resources.rst:
--------------------------------------------------------------------------------
  1 | =========
  2 | Resources
  3 | =========
  4 | 
  5 | The fundamental concept in any RESTful API is the *resource*.  A resource is
  6 | an object with a type, associated data, relationships to other resources, and
  7 | a set of methods that operate on it. It is similar to an object
  8 | instance in an object-oriented programming language, with the important
  9 | difference that only a few standard methods are defined for the resource
 10 | (corresponding to the standard HTTP GET, POST, PUT and DELETE methods), while
 11 | an object instance typically has many methods.
 12 | 
 13 | Resources can be grouped into *collections*. Each collection is homogeneous so
 14 | that it contains only one type of resource, and unordered. Resources can also
 15 | exist outside any collection. In this case, we refer to these resources as
 16 | *singleton resources*. Collections are themselves resources as well.
 17 | 
 18 | Collections can exist globally, at the top level of an API, but can also be
 19 | contained inside a single resource. In the latter case, we refer to these
 20 | collections as *sub-collections*. Sub-collections are usually used to express
 21 | some kind of "contained in" relationship. We go into more detail on this in
 22 | :doc:`relationships`.
 23 | 
 24 | The diagram below illustrates the key concepts in a RESTful API.
 25 | 
 26 | .. image:: images/concepts.png
 27 |    :width: 90%
 28 |    :align: center
 29 | 
 30 | We call information that describes available resources types, their behavior,
 31 | and their relationships the *resource model* of an API. The resource model can
 32 | be viewed as the RESTful mapping of the application data model.
 33 | 
 34 | Resource Data
 35 | =============
 36 | 
 37 | Resources have data associated with them. The richness of data that can be
 38 | associated with a resource is part of the *resource model* for an API. It
 39 | defines for example the available data types and their behavior.
 40 | 
 41 | Based on my experience, I have developed a strong conviction that the JSON
 42 | data model has just the right "richness" so that it is an ideal data model for
 43 | RESTful resources. I would recommend that everybody use it.
 44 | 
 45 | In JSON, just three types of data exist:
 46 | 
 47 | * scalar (number, string, boolean, null).
 48 | * array
 49 | * object
 50 | 
 51 | Scalar types have just a single value. Arrays contain an ordered list of
 52 | values of arbitrary type. Objects consist of a unordered set of key:value
 53 | pairs (also called attributes, not to be confused with XML attributes), where
 54 | the key is a string and the value can have an arbitrary type. For more
 55 | detailed information on JSON, see the `JSON web site <http://www.json.org/>`_.
 56 | 
 57 | Why the strong preference for JSON? In my view, JSON has the right balance
 58 | between expressiveness, and broad availability. The three types of data
 59 | (scalars, arrays and objects) are powerful enough to describe in a natural way
 60 | virtually all the data that you might want to expose as resource, and at the
 61 | same time these types are minimal enough so that almost any modern language
 62 | has built-in support for them.
 63 | 
 64 | XML would be the other obvious contender. Actually, in the final incarnation
 65 | of the RHEV-M API, XML is used to describe resources, via an XMLSchema
 66 | definition.  With hindsight, I believe that the XML data model is a bad choice
 67 | for a RESTful API. On one side, it is too rich, and on the other side, it
 68 | lacks features. XML, as an SGML off-shoot, is in my view great for
 69 | representing structured documents, but not for representing structured data.
 70 | 
 71 | Features of XML that are too rich include:
 72 | 
 73 | 1. Attributes vs elements. An XML element can have both attributes as well as
 74 |    sub-elements. A data item associated with a resource could be encoded in
 75 |    either one, and it would not be clear beforehand which one a client or a
 76 |    server should use.
 77 | 2. Relevance of order. The order between child-elements is relevant in XML. It
 78 |    is not natural in my view for object attributes to have ordering.
 79 | 
 80 | The limitations of the XML data model are:
 81 | 
 82 | 1. Lack of types. Elements in XML documents do not have types, and in order to
 83 |    use types, one would have to use e.g. XMLSchema. XMLSchema unfortunately is
 84 |    a strong contender for the most convoluted specification ever written.
 85 | 2. Lack of lists. XML cannot natively express lists. This can lead to issues
 86 |    whereby it is not clear whether a certain element is supposed to be a list
 87 |    or an object, and where that element ends up being both.
 88 | 
 89 | Application Data
 90 | ----------------
 91 | 
 92 | We define the data that can be associated with a resource in terms of the JSON
 93 | data model, using the following mapping rules:
 94 | 
 95 | 1. Resources are modeled as a JSON object. The type of the resource is
 96 |    stored under the special key:value pair "_type".
 97 | 2. Data associated with a resource is modeled as key:value pairs on the
 98 |    JSON object. To prevent naming conflicts with internal key:value pairs,
 99 |    keys must not start with "_".
100 | 3. The values of key:value pairs use any of the native JSON data types of
101 |    string, number, boolean, null, or arrays thereof. Values can also be
102 |    objects, in which case they are modeling nested resources.
103 | 4. Collections are modeled as an array of objects.
104 | 
105 | We will also refer to key:value pairs as attributes of the JSON object, and we
106 | will be sloppy and use that same term for data items associated with resources,
107 | too. This use of attributes is not to be confused with XML attributes.
108 | 
109 | REST Metadata
110 | -------------
111 | 
112 | In addition to exposing application data, resources also include other
113 | information that is specific to the RESTful API. Such information includes
114 | URLs and relationships.  
115 | 
116 | The following table lists generic attributes that are defined and have a
117 | specific meaning on all resources. They should not be used for mapping
118 | application model attributes.
119 | 
120 | =========  ======  ==========================================
121 | Attribute  Type                     Meaning
122 | =========  ======  ==========================================
123 | id         String  Identifies the unique ID of a resource.
124 | href       String  Identifies the URL of the current resource.
125 | link       Object  Identifies a relationship for a resource.
126 |                    This attribute is itself an object and has
127 |                    "rel" "href" attributes.
128 | =========  ======  ==========================================
129 | 
130 | Other Data
131 | ----------
132 | 
133 | Apart from application data, and REST metadata, sometimes other data is
134 | required as well. This is usually "RPC like" data where a setting is needed
135 | for an operation, and where that setting will not end up being part of the
136 | resource itself.
137 | 
138 | One example that I can give here is where a resource creation needs a
139 | reference to another resource that is used during the creation, but where that
140 | other resource will not become part of the resource itself.
141 | 
142 | It is the responsibility of the API code to merge the application data
143 | together with the REST metadata and the other data into a single resource,
144 | resolving possible naming conflicts that may arise.
145 | 
146 | Representations
147 | ===============
148 | 
149 | We have defined resources, and defined the data associated with them in terms
150 | of the JSON data model. However, these resources are still abstract entities.
151 | Before they can be communicated to a client over an HTTP connection, they need
152 | to be serialized to a textual representation. This representation can then be
153 | included as an entity in an HTTP message body.
154 | 
155 | The following representations are common for resources. The table also lists
156 | the appropriate content-type to use:
157 | 
158 | ====  ===========================================================
159 | Type          Content-Type
160 | ====  ===========================================================
161 | JSON  | application/x-resource+json
162 |       | application/x-collection+json
163 | YAML  | application/x-resource+yaml
164 |       | application/x-collection+yaml
165 | XML   | application/x-resource+xml
166 |       | application/x-collection+xml
167 | HTML  text/html
168 | ====  ===========================================================
169 | 
170 | Note: all these content types use the "x-" experimental prefix that is allowed
171 | by `RFC2046 <http://www.ietf.org/rfc/rfc2046.txt>`_.
172 | 
173 | JSON Format
174 | -----------
175 | 
176 | Formatting a resource to JSON is trivial because the data model of a
177 | resource is defined in terms of the JSON model. Below we give an example of a
178 | JSON serialization of a virtual machine::
179 | 
180 |   {
181 |     "_type": "vm",
182 |     "name": "A virtual machine",
183 |     "memory": 1024,
184 |     "cpu": {
185 |       "cores": 4,
186 |       "speed": 3600
187 |     },
188 |     "boot": {
189 |       "devices": ["cdrom", "harddisk"]
190 |     }
191 |   }
192 | 
193 | 
194 | YAML Format
195 | -----------
196 | 
197 | Formatting to YAML is only slightly different than representing a resource in
198 | JSON. The resource type that is stored under the "_type" key/value pair is
199 | serialized as a YAML "!type" annotation instead. The same virtual machine as
200 | above, now in YAML format::
201 | 
202 |   !vm
203 |   name: A virtual machine
204 |   memory: 1024
205 |   cpu:
206 |     cores: 4
207 |     speed: 3600
208 |   boot:
209 |     devices:
210 |     - cdrom
211 |     - harddisk
212 | 
213 | XML Format
214 | ----------
215 | 
216 | XML is the most complex representation format due to both its complexity as
217 | well as its limitations. I recommend the following rules:
218 | 
219 | * Resources are mapped to XML elements with a tag name equal to the resource
220 |   type.
221 | * Attributes of resources are mapped to XML child elements with the tag name
222 |   equal to the attribute name.
223 | * Scalar values are stored as text nodes. A special "type" attribute on the
224 |   containing element should be used to refer to an `XML Schema Part 2
225 |   <http://www.w3.org/TR/xmlschema-2/>`_ type definition.
226 | * Lists should be stored as a single container element with child elements for
227 |   each list item. The tag of the container element should be the English
228 |   plural of the attribute name. The item tag should be the English singular of
229 |   the attribute name. Lists should have the "xd:list" type annotation.
230 | 
231 | The same VM again, now in XML::
232 | 
233 |   <vm xmlns:xs="http://www.w3.org/2001/XMLSchema">
234 |     <name type="xs:string">My VM</name>
235 |     <memory type="xs:int">1024</memory>
236 |     <cpu>
237 |       <cores type="xs:int">4</cores>
238 |       <speed type="xs:int">3600</speed>
239 |     </cpu>
240 |     <boot>
241 |       <devices type="xs:list">
242 |         <device type="xs:string">cdrom</device>
243 |         <device type="xs:string">harddisk</device>
244 |       </devices>
245 |     </boot>
246 |   </vm>
247 | 
248 | 
249 | HTML Format
250 | -----------
251 | 
252 | The exact format of a HTML response can be API dependent.  HTML is for human
253 | consumption, and the only requirement is therefore that it be easy to
254 | understand. A simple implementation may choose the following representation:
255 | 
256 | * For a collection, a <table> with a column per attribute where each object
257 |   is listed in a separate row.
258 | * For a resource, a <table> with two columns, one with all the attribute
259 |   names, one with the corresponding attribute value.
260 | 
261 | Content-Types
262 | =============
263 | 
264 | As can be seen above, I am advocating the use of a generic content types
265 | "application/x-resource+format" and "application/x-collection+format". In my
266 | view this represents the right middle ground between two extremes that are
267 | commonly found in RESTful APIs:
268 | 
269 | Some RESTful APIs only use the "bare" XML, JSON or YAML content types. An
270 | example of such as API is the Red Hat Enterprise Virtualization API. In this
271 | case, the content type expresses nothing but the fact that an entity is in
272 | XML, JSON or YAML format. In my view, this is not sufficient. Resources and
273 | collections have some specific semantics around for example the use of "href"
274 | attributes, "link" attributes, and types. Therefore, these are a
275 | specialization of XML, JSON and YAML and should be defined as such.
276 | 
277 | Other RESTful APIs define a content-type for every resource type that exists
278 | in the resource model. Examples of such APIs include for example VMware's
279 | `vSphere Director API <http://www.vmware.com/pdf/vcd_10_api_guide.pdf>`_. In
280 | my view, this is not proper either. Specifying detailed content types invites
281 | both the API implementer, as well as a client implementer to think about these
282 | types as having specific interfaces. In my view though, all resources should
283 | share the same basic interface, which is defined by the RESTful design
284 | principles and expressed by the "application/x-resource" content type.
285 | 
286 | One reason that is sometimes given in favor of defining detailed content types
287 | is that this way, the content type can be associated with a specific
288 | definition in some type definition language (such as XMLSchema). This,
289 | supposedly, facilitates client auto-discovery because a client can know
290 | available attributes for a certain type. I go into a lot of detail on this
291 | topic in :doc:`forms` but the summary is that I do not agree with this
292 | argument.
293 | 
294 | Selecting a Representation Format
295 | ---------------------------------
296 | 
297 | Clients can express their preference for a certain representation format using
298 | the HTTP "Accept" header. The HTTP RFC defines an `elaborate set of rules
299 | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1>`_ in which
300 | multiple formats can be requested, each with its own priority. In the
301 | following example, the client tells the API that it accepts only YAML input:
302 | 
303 | .. code-block:: none
304 | 
305 |   GET /api/collection
306 |   Accept: application/x-collection+yaml
307 | 


--------------------------------------------------------------------------------
/scope.rst:
--------------------------------------------------------------------------------
  1 | ===========================
  2 | The Job of the API Designer
  3 | ===========================
  4 | 
  5 | Before we dive fully into RESTful API design, it makes sense to look in a
  6 | little more detail what the job of a RESTful API designer is.
  7 | 
  8 | APIs don't exist in isolation. Instead, APIs expose functionality of an
  9 | application or service that exists independently of the API. In my view, the
 10 | job of the RESTful API designer is two-fold.
 11 | 
 12 | 1. Understanding enough of the important details of the application for which
 13 |    an API is to be created, so that an informed decision can be made as to what
 14 |    functionality needs to be exposed, how it needs to be exposed, and what
 15 |    functionality can instead be left out.
 16 | 2. Modeling this functionality in an API that addresses all use cases that
 17 |    come up in the real world, following the RESTful principles as closely as
 18 |    possible.
 19 | 
 20 | There are three distinct components involved in RESTful API design: the
 21 | application, the API code, and the client. The image above illustrates how
 22 | these three components interact.
 23 | 
 24 | .. image:: images/scope.png
 25 |    :width: 90%
 26 |    :align: center
 27 | 
 28 | 
 29 | The Application
 30 | ===============
 31 | 
 32 | The application for which an API is to be provided exists independently of
 33 | that API. Maybe the application has a GUI, and you have a requirement to add a
 34 | programmatic interface to it. Or maybe the application was designed under the
 35 | assumption that it would be accessed only via the API you are designing.
 36 | 
 37 | Like any application, the application for which the API is to be created
 38 | contains state. That state is dynamic, and will change due to various
 39 | operations that are executed on it. This state, and the operations on it, need
 40 | to be modeled and exposed, and will form the API you are designing.
 41 | 
 42 | The easiest way to think about the application state, is to assume that it is
 43 | is described by an *application data model*, which can be described by an
 44 | *Entity-Relationship diagram*. The ER-Diagram lists the details of the
 45 | *entities* (I will call them  *objects*) in the application state, and the
 46 | *relationships* between them.
 47 | 
 48 | In some cases, it is very easy to create the ER diagram. For example, in case
 49 | of a web application that stores all its state in a database, it can be
 50 | trivially created from the schema of the database. In other cases where there
 51 | is not such a precise definition, the job of the API designer becomes a little
 52 | more difficult. In such a case it would actually make sense to create an ER
 53 | diagram for the application in question. That is a useful exercise in its own
 54 | right, as it will make you better understand the application you're designing the API
 55 | for. But more importantly, it will also help you in designing a good
 56 | RESTful API. We will talk more about that in a minute. Going forward, I will
 57 | assume that an ER diagram is available.
 58 | 
 59 | In addition to understanding the application data model, and the operations on
 60 | it, you of course need an entry point into the application that allows you to
 61 | access and change the application state. This "way in" is fully application
 62 | dependent and could take many forms. We will call this "way in" the
 63 | *application interface*.  Formally, this application interface could be
 64 | considered an API as well. The difference, though, is that this interface is
 65 | usually not intended for external consumption or even fully documented.  In
 66 | order not to introduce any confusion, we will not refer to this interface as
 67 | an API: that term will be reserved for the RESTful API that is being designed.
 68 | 
 69 | 
 70 | The API Code
 71 | ============
 72 | 
 73 | The job of the API code is to access the application state, as well as the
 74 | operations on that state, via the application interface, and expose it as a
 75 | RESTful API. In between the application interface and the RESTful API, there
 76 | is a transformation step that adapts the application data model and makes it
 77 | comply with the RESTful architecture style.
 78 | 
 79 | The result of this transformation would be RESTful *resources*, operations on
 80 | those resources, and relationships between the resources. All of these are
 81 | described by what we call the RESTful *resource model*.
 82 | 
 83 | Resources are the foundation behind any RESTful API, and we will go into a lot
 84 | of detail on them in :doc:`resources`. For now, just think of resources as
 85 | being very similar to the entities from the ER diagram (which is why I
 86 | encouraged you to create an ER diagram for your application in case it didn't
 87 | exist).
 88 | 
 89 | Relationships between resources are expressed as hyperlinks in the
 90 | representation of the resource. This is one of the `fundamental principles
 91 | <http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven>`_ of
 92 | RESTful API design. Resources also respond to a very limited set of operations
 93 | (usually just 4), which is a second principle of the RESTful architectural
 94 | style.
 95 | 
 96 | When transforming objects from the application data model to RESTful
 97 | resources, you may find it useful to define two utility functions:
 98 | 
 99 | .. function:: to_resource()
100 | 
101 |    This function is assumed to take an object from the application data model,
102 |    and convert it into a resource.
103 | 
104 | .. function:: from_resource()
105 | 
106 |    This function is assumed to take a resource, and translate it into
107 |    an object in the application data model.
108 | 
109 | We don't discuss these methods further, other than mentioning that these can
110 | be rather simple functions if the application data model is similar to the
111 | resource model you're exposing, and can be quite complicated if they are very
112 | different.
113 | 
114 | 
115 | The Client
116 | ==========
117 | 
118 | The client consumes the RESTful API via the standard HTTP protocol. In theory,
119 | the service could be provided on top of other protocols as well.
120 | Since HTTP is so ubiquitous, however, it is not certain how valuable such a mapping to
121 | another protocol would be in the real world. Therefore, this essay limits
122 | itself to describing our RESTful protocol in terms of HTTP.
123 | 
124 | Clients would typically use an HTTP library to access the RESTful API. HTTP
125 | has become a moderately complex protocol, and very good libraries exist for
126 | many target platforms / languages. It therefore makes a lot of sense to use
127 | one of those libraries.
128 | 
129 | In some cases, it may make sense to use a generic REST library on top of an
130 | HTTP library. However, since there are so many different conventions in
131 | RESTful APIs, this library may actually be specific to the API that you are
132 | consuming.
133 | 


--------------------------------------------------------------------------------
/urls.rst:
--------------------------------------------------------------------------------
  1 | ====
  2 | URLs
  3 | ====
  4 | 
  5 | Entry Point
  6 | ===========
  7 | 
  8 | A RESTful API needs to have one and exactly one entry point. The URL of the
  9 | entry point needs to be communicated to API clients so that they can find the
 10 | API.
 11 | 
 12 | Technically speaking, the entry point can be seen as a singleton resource that
 13 | exists outside any collection. It is common for the entry point to contain some
 14 | or all of the following information:
 15 | 
 16 | * Information on API version, supported features, etc.
 17 | * A list of top-level collections.
 18 | * A list of singleton resources.
 19 | * Any other information that the API designer deemed useful, for example a
 20 |   small summary of operating status, statistics, etc.
 21 | 
 22 | URL Structure
 23 | =============
 24 | 
 25 | Each collection and resource in the API has its own URL. URLs should never be
 26 | constructed by an API client. Instead, the client should only follow links that
 27 | are generated by the API itself.
 28 | 
 29 | The recommended convention for URLs is to use alternate collection / resource
 30 | path segments, relative to the API entry point. This is best described by
 31 | example. The table below uses the ":name" URL variable style from Rail's
 32 | "Routes" implementation.
 33 | 
 34 | ==============================  =============================================
 35 |               URL                               Description
 36 | ==============================  =============================================
 37 | /api                            The API entry point
 38 | /api/:coll                      A top-level collection named "coll"
 39 | /api/:coll/:id                  The resource "id" inside collection "coll"
 40 | /api/:coll/:id/:subcoll         Sub-collection "subcoll" under resource "id"
 41 | /api/:coll/:id/:subcoll/:subid  The resource "subid" inside "subcoll"
 42 | ==============================  =============================================
 43 | 
 44 | Even though sub-collections may be arbitrarily nested, in my experience, you
 45 | want to keep the depth limited to 2, if possible. Longer URLs are more
 46 | difficult to work with when using simple command-line tools like `curl
 47 | <http://curl.haxx.se/>`_.
 48 | 
 49 | Relative vs Absolute
 50 | ====================
 51 | 
 52 | It is strongly recommended that the URLs generated by the API should be
 53 | absolute URLs.
 54 | 
 55 | The reason is mostly for ease of use by the client, so that it never has to
 56 | find out the correct base URI for a resource, which is needed to interpret a
 57 | relative URL. The `URL RFC <http://tools.ietf.org/html/rfc3986#section-5.1>`_
 58 | specifies the algorithm for determining a base URL, which is rather complex.
 59 | One of the options for finding the base URL is to use the URL of the resource
 60 | that was requested. Since a resource may appear under multiple URLs (for
 61 | example, as part of a collection, or stand-alone), it would be a significant
 62 | overhead to a client to remember where he retrieved a representation from. By
 63 | using absolute URLs, this problem doesn't present itself.
 64 | 
 65 | URL Templates
 66 | =============
 67 | 
 68 | A `draft standard <http://tools.ietf.org/html/draft-gregorio-uritemplate-05>`_
 69 | for URL templates exists. URL templates can be useful in link attributes
 70 | where the target URL takes query arguments. It is recommended though to make
 71 | only conservative use of these. So far the only good use case I have come
 72 | across is when searching in a collection. In that case, it seems fair that the
 73 | search criteria can be specified as GET style query arguments appended to the
 74 | collection URL.
 75 | 
 76 | I would recommend to only use the "literal expansion" part of the URL
 77 | templates spec, because the "expression expansion" part adds too much
 78 | complexity to a client in my view, for very little benefit.
 79 | 
 80 | Variants
 81 | ========
 82 | 
 83 | Sometimes you need to work on a variant of a resource. In our RHEV-M API for
 84 | example, some attributes on a virtual machine can be updated while a virtual
 85 | machine is running. This amounts to a hot plug/unplug of the resource, which
 86 | is a different operation altogether from changing the saved representation. A
 87 | nice way to implement this is using ";variant" identifier in a URL. For
 88 | example:
 89 | 
 90 | ======================  =============================================
 91 |           URL                            Description
 92 | ======================  =============================================
 93 | /api/:coll/:id;saved    Identifies the saved variant of a resource.
 94 | /api/:coll/:id;current  Identifies the current variant of a resource.
 95 | ======================  =============================================
 96 | 
 97 | The use of the semicolon to provide options that are specific to a path
 98 | segment is explicitly alowed in `RFC3986
 99 | <http://tools.ietf.org/html/rfc3986#section-3.3>`_ The advantage over using a
100 | "?variant" query argument is that this format is specific to a path segment
101 | only, and would allow you to e.g. work on the saved variant of a sub-resource
102 | in a sub-collection of the current variant of another resource.
103 | 


--------------------------------------------------------------------------------