TOC (2)

Author: lambda2

README.md

@@ -7,32 +7,30 @@ A 21th century specification proposal for Rest API's
 
 ---------------
 
-#### This specification is intended to establish an agreement on the behavior of an API, no matters the format (json, xml, etc...).
-
-
-- 1. Design
-- 2. Formatting
-- 3. Security
-- 4. Verbs
-  - Fallback header
-  - Location header
-  - Resource on update and create actions
-- 5. Status codes
-- 6. Errors
-- 7. Parameters
-- 8. Custom HTTP headers
-- 9. Versioning
-- 10. Pagination
-- 11. Filtering
-- 12. Sorting
-- 13. Searching
-- 14. Embedding
-- 15. Selecting
-- 16. Caching
-- 17. Asynchronous processing
-- Sources
-
-### 1. Design
+### This specification is intended to establish an agreement on the behavior of an API, no matters the format (json, xml, etc...).
+
+## Table of contents
+
+1. [Design](#1-design)
+2. [Formatting](#2-formatting)
+3. [Security](#3-security)
+4. [Verbs](#4-verbs)
+5. [Status codes](#5-status-codes)
+6. [Errors](#6-errors)
+7. [Parameters](#7-parameters)
+8. [Custom HTTP headers](#8-custom-http-headers)
+9. [Versioning](#9-versioning)
+10. [Pagination](#10-pagination)
+11. [Filtering](#11-filtering)
+12. [Sorting](#12-sorting)
+13. [Searching](#13-searching)
+14. [Embedding](#14-embedding)
+15. [Selecting](#15-selecting)
+16. [Caching](#16-caching)
+17. [Asynchronous processing](#17-asynchronous-processing)
+[Sources](#sources)
+
+## 1. Design
 
 The API must embrace RESTful design principles. It must be resource-based, and each resource representation must contain enough information to modify or delete the resource on the server, provided it has permission to do so.
 
@@ -48,20 +46,19 @@ The API must embrace RESTful design principles. It must be resource-based, and e
 
   > You don't want to deal with complex pluralization (e.g., foot/feet, child/children, people/people). Keep it simple.
 
-### 2. Formatting
+## 2. Formatting
 
 - Dates must be returned in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
-- Geographic coordinates must be returned in `[-]d.d, [-]d.d` format (e.g., 12.3456, -98.7654).
 
-> TODO: more ?
+- Geographic coordinates must be returned in `[-]d.d, [-]d.d` format (e.g., 12.3456, -98.7654).
 
-### 3. Security
+## 3. Security
 
 - The API must be served over SSL, using `https`. It must not redirect on non-SSL urls.
 
   > Always using SSL guaranteed encrypted communications, and allow use of simple access tokens.
 
-### 4. Verbs
+## 4. Verbs
 
 |       Verb   |                     Description                       |
 |--------------|-------------------------------------------------------|
@@ -70,21 +67,21 @@ The API must embrace RESTful design principles. It must be resource-based, and e
 |  PATCH / PUT | Used for updating resources.                          |
 |  DELETE      | Used for deleting resources.                          |
 
-#### Fallback header
+### Fallback header
 
 The HTTP client that doesn't support PUT, PATCH or DELETE requests must send a POST request with an `X-HTTP-Method-Override` header specifying the desired verb.
 
 The server must correctly handle this header. When it is set, it take precedence over the original request method.
 
-#### Location header
+### Location header
 
 When a resource is created (with a `POST` request), the response must contain a `Location` header with the link of the new resource.
 
-#### Resource on update and create actions
+### Resource on update and create actions
 
 When a resource is created or modified (e.g., with a POST, PUT or PATCH request), the response must contain the created or updated respresentation of the resource.
 
-### 5. Status codes
+## 5. Status codes
 
 **The API must uses descriptive HTTP response codes to indicate the success or failure of request.**
 
@@ -113,7 +110,7 @@ The server must respond with the following status codes, according to the situat
 | 503 Service Unavailable   | The server is currently unable to handle the request.                     |
 
 
-### 6. Errors
+## 6. Errors
 
 - All errors in the 4xx must return a body containing a `error` key, containing the error code.
 
@@ -154,7 +151,7 @@ Content-Type: application/json
 ```
 
 
-### 7. Parameters
+## 7. Parameters
 
 Resource creation or update parameters must be wrapped in an object as the singular name of the resource.
 
@@ -186,13 +183,13 @@ Content-Type: application/json
 ```
 
 
-### 8. Custom HTTP headers
+## 8. Custom HTTP headers
 
 All non-standard HTTP headers must begin by a `X-`.
 
 For example, for rate limiting, the `X-Rate-Limit-Limit`, `X-Rate-Limit-Remaining` and `X-Rate-Limit-Reset` headers should be used.
 
-### 9. Versioning
+## 9. Versioning
 
 The API must be versioned, and must not have breaking changes whitout version change.
 
@@ -221,7 +218,7 @@ X-Version: 3.1
 }
 ```
 
-### 10. Pagination
+## 10. Pagination
 
 Requests for collections should be paginated, and return a limited number of results.
 
@@ -266,7 +263,7 @@ X-Total: 4
 ]
 ```
 
-### 11. Filtering
+## 11. Filtering
 
 The client should be able to filter resource collections using the `filter` parameter. In this case, only the fields matching the given filter(s) will be returned.
 
@@ -293,7 +290,7 @@ Content-Type: application/json
 ```
 
 
-### 12. Sorting
+## 12. Sorting
 
 The client should be able to sort resource collections according to one or more fields using the `sort` parameter. The value for `sort` must represent sort fields.
 
@@ -339,7 +336,7 @@ Content-Type: application/json
 
 If the server does not support sorting as specified in the query parameter `sort`, it must return a `400 Bad Request` status code.
 
-### 13. Searching
+## 13. Searching
 
 The client should be able to search on resource collections fields using the `search` parameter. In this case, only the fields matching the given search(s) will be returned.
 
@@ -377,7 +374,7 @@ Content-Type: application/json
 
 A global search on a resource collection should be implemented using directly a value instead of a hash for the `search` parameter.
 
-### 14. Embedding
+## 14. Embedding
 
 The client should be able to include data related to (or referenced) from the resource being requested using the `embed` parameter. The value of the `embed` parameter must be a comma separated list of fields to be embedded. Dot-notation must be used to refer to sub-fields.
 
@@ -429,7 +426,7 @@ Content-Type: application/json
 ]
 ```
 
-### 15. Selecting
+## 15. Selecting
 
 The client should be able to select only specific fields in the response using the `fields` parameter. In this case, only the requested fields will be returned.
 
@@ -466,11 +463,11 @@ Content-Type: application/json
 If the server does not support selection as specified in the query parameter `fields`, it must return a `400 Bad Request` status code.
 
 
-### 16. Caching
+## 16. Caching
 
 Server should generate a [ETag header](http://en.wikipedia.org/wiki/HTTP_ETag) containing a hash or checksum of the representation. This value should change whenever the output representation changes.
 
-### 17. Asynchronous processing
+## 17. Asynchronous processing
 
 When a resource creation or update is asynchronously processed, the request should return a `202 Accepted` status code with a link in the `Content-Location` header which should redirect to the resource when the job processing is done.
 
@@ -506,7 +503,7 @@ Content-Type: application/json
 Location: https://api.example.com/movies/3
 ```
 
-### Sources
+## Sources
 
 - [Nouns are good, verbs are bad](http://apigee.com/about/blog/technology/restful-api-design-nouns-are-good-verbs-are-bad)
 - [Principles of good RESTful API Design](https://codeplanet.io/principles-good-restful-api-design/)