[Doc] Add example API calls to ra-data-simplerest

packages/ra-data-simple-rest/README.md

@@ -14,6 +14,8 @@ npm install --save ra-data-simple-rest
 
 This Data Provider fits REST APIs using simple GET parameters for filters and sorting. This is the dialect used for instance in [FakeRest](https://github.com/marmelab/FakeRest).
 
+### Request Format
+
 | Method             | API calls                                                                               |
 | ------------------ | --------------------------------------------------------------------------------------- |
 | `getList`          | `GET http://my.api.url/posts?sort=["title","ASC"]&range=[0, 24]&filter={"title":"bar"}` |
@@ -26,6 +28,10 @@ This Data Provider fits REST APIs using simple GET parameters for filters and so
 | `delete`           | `DELETE http://my.api.url/posts/123`                                                    |
 | `deleteMany`       | Multiple calls to `DELETE http://my.api.url/posts/123`                                  |
 
+### Response Format
+
+An `id` field is required in all records. You can also set [custom identifier or primary key for your resources](https://marmelab.com/react-admin/FAQ.html#can-i-have-custom-identifiersprimary-keys-for-my-resources)
+
 The API response when called by `getList` should look like this:
 
 ```json
@@ -38,8 +44,6 @@ The API response when called by `getList` should look like this:
 ]
 ```
 
-An `id` field is required. You can also set [custom identifier or primary key for your resources](https://marmelab.com/react-admin/FAQ.html#can-i-have-custom-identifiersprimary-keys-for-my-resources)
-
 **Note**: The simple REST data provider expects the API to include a `Content-Range` header in the response to `getList` calls. The value must be the total number of resources in the collection. This allows react-admin to know how many pages of resources there are in total, and build the pagination controls.
 
 ```txt
@@ -52,6 +56,214 @@ If your API is on another domain as the JS code, you'll need to whitelist this h
 Access-Control-Expose-Headers: Content-Range
 ```
 
+## Example Calls
+
+### getList
+
+```
+## DataProvider
+dataProvider.getList('posts', {
+    sort: { field: 'title', order: 'ASC' },
+    pagination: { page: 1, perPage: 5 },
+    filter: { author_id: 12 }
+})
+
+## Request
+GET http://my.api.url/posts?sort=["title","ASC"]&range=[0, 4]&filter={"author_id":12}
+
+## Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+Content-Range: posts 0-4/27
+[
+    { "id": 126, "title": "allo?", "author_id": 12 },
+    { "id": 127, "title": "bien le bonjour", "author_id": 12 },
+    { "id": 124, "title": "good day sunshine", "author_id": 12 },
+    { "id": 123, "title": "hello, world", "author_id": 12 },
+    { "id": 125, "title": "howdy partner", "author_id": 12 }
+]
+```
+
+### getOne
+
+```
+## DataProvider
+dataProvider.getOne('posts', { id: 123 })
+
+## Request
+GET http://my.api.url/posts/123
+
+## Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+{ "id": 123, "title": "hello, world", "author_id": 12 }
+```
+
+### getMany
+
+```
+## DataProvider
+dataProvider.getMany('posts', { ids: [123, 124, 125] })
+
+## Request
+GET http://my.api.url/posts?filter={"ids":[123,124,125]}
+
+## Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+[
+    { "id": 123, "title": "hello, world", "author_id": 12 },
+    { "id": 124, "title": "good day sunshine", "author_id": 12 },
+    { "id": 125, "title": "howdy partner", "author_id": 12 }
+]
+```
+
+### getManyReference
+
+```
+## DataProvider
+dataProvider.getManyReference('comments', {
+    target: 'post_id',
+    id: 12,
+    pagination: { page: 1, perPage: 25 },
+    sort: { field: 'created_at', order: 'DESC' }
+    filter: {}
+})
+
+## Request
+GET http://my.api.url/comments?sort=["created_at","DESC"]&range=[0, 24]&filter={"post_id":123}
+
+## Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+Content-Range: comments 0-1/2
+[
+    { "id": 667, "title": "I agree", "post_id": 123 },
+    { "id": 895, "title": "I don't agree", "post_id": 123 }
+]
+```
+
+### create
+
+```
+## DataProvider
+dataProvider.create('posts', {
+    data: { title: "hello, world", author_id: 12 }
+})
+
+## Request
+POST http://my.api.url/posts
+{ "title": "hello, world", "author_id": 12 }
+
+## Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+{ "id": 123, "title": "hello, world", "author_id": 12 }
+```
+
+### update
+
+```
+## DataProvider
+dataProvider.update('posts', {
+    id: 123,
+    data: { title: "hello, world" },
+    previousData: { title: "hello, partner", author_id: 12 }
+})
+
+## Request
+PUT http://my.api.url/posts/123
+{ "title": "hello, world!" }
+
+## Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+{ "id": 123, "title": "hello, world!", "author_id": 12 }
+```
+
+### updateMany
+
+```
+## DataProvider
+dataProvider.updateMany('posts', {
+    ids: [123, 124, 125],
+    data: { title: "hello, world" },
+})
+
+## Request 1
+PUT http://my.api.url/posts/123
+{ "title": "hello, world!" }
+
+## Response 1
+HTTP/1.1 200 OK
+Content-Type: application/json
+{ "id": 123, "title": "hello, world!", "author_id": 12 }
+
+## Request 2
+PUT http://my.api.url/posts/124
+{ "title": "hello, world!" }
+
+## Response 2
+HTTP/1.1 200 OK
+Content-Type: application/json
+{ "id": 124, "title": "hello, world!", "author_id": 12 }
+
+## Request 3
+PUT http://my.api.url/posts/125
+{ "title": "hello, world!" }
+
+## Response 3
+HTTP/1.1 200 OK
+Content-Type: application/json
+{ "id": 125, "title": "hello, world!", "author_id": 12 }
+```
+
+### delete
+
+```
+## DataProvider
+dataProvider.delete('posts', { id: 123 })
+
+## Request
+DELETE http://my.api.url/posts/123
+
+## Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+{ "id": 123, "title": "hello, world", "author_id": 12 }
+```
+
+### deleteMany
+
+```
+## DataProvider
+dataProvider.deleteMany('posts', { ids: [123, 124, 125] })
+
+## Request 1
+DELETE http://my.api.url/posts/123
+
+## Response 1
+HTTP/1.1 200 OK
+Content-Type: application/json
+{ "id": 123, "title": "hello, world", "author_id": 12 }
+
+## Request 2
+DELETE http://my.api.url/posts/124
+
+## Response 2
+HTTP/1.1 200 OK
+Content-Type: application/json
+{ "id": 124, "title": "good day sunshine", "author_id": 12 }
+
+## Request 3
+DELETE http://my.api.url/posts/125
+
+## Response 3
+HTTP/1.1 200 OK
+Content-Type: application/json
+{ "id": 125, "title": "howdy partner", "author_id": 12 }
+```
+
 ## Usage
 
 ```jsx
@@ -63,15 +275,15 @@ import simpleRestProvider from 'ra-data-simple-rest';
 import { PostList } from './posts';
 
 const App = () => (
-    <Admin dataProvider={simpleRestProvider('http://path.to.my.api/')}>
+    <Admin dataProvider={simpleRestProvider('http://my.api.url/')}>
         <Resource name="posts" list={PostList} />
     </Admin>
 );
 
 export default App;
 ```
 
-### Adding Custom Headers
+## Adding Custom Headers
 
 The provider function accepts an HTTP client function as second argument. By default, they use react-admin's `fetchUtils.fetchJson()` as HTTP client. It's similar to HTML5 `fetch()`, except it handles JSON decoding and HTTP error codes automatically.
 
@@ -129,7 +341,7 @@ The solution is to use another http header to return the number of collection's
 Access-Control-Expose-Headers: X-Total-Count
 ```
 
-* Use the third parameter of `simpleRestProvider` to specify the name of the header to use :
+* Use the third parameter of `simpleRestProvider` to specify the name of the header to use:
 
 ```jsx
 // in src/App.js
@@ -141,7 +353,7 @@ import simpleRestProvider from 'ra-data-simple-rest';
 import { PostList } from './posts';
 
 const App = () => (
-    <Admin dataProvider={simpleRestProvider('http://path.to.my.api/', fetchUtils.fetchJson, 'X-Total-Count')}>
+    <Admin dataProvider={simpleRestProvider('http://my.api.url/', fetchUtils.fetchJson, 'X-Total-Count')}>
         <Resource name="posts" list={PostList} />
     </Admin>
 );