Note that there are some explanatory texts on larger screens.

plurals
  1. PO
    primarykey
    data
    text
    <p>Using your example, here is how I might do it using JSON and HAL.</p> <p>A root page:</p> <p><strong>Request:</strong></p> <pre><code>GET / HTTP/1.1 Host: example.com </code></pre> <p><strong>Response:</strong></p> <pre><code>200 OK Content-Type: application/hal+json { "_links": { "self": { "href": "/" }, "students": { "href": "/students" }, "classes": { "href": "/classes" }, "students-with-classes": { "href": "/students?expand" }, } } </code></pre> <p>Creating a new student would be documented on the <code>students</code> relation via posting to the provided href. Presumably I would have previously followed the <code>classes</code> link relation to get the link to class A so that I can include it when adding a user.</p> <p><strong>Request:</strong></p> <pre><code>POST /students HTTP/1.1 Content-Type: application/json { name: "Foo", surname: "Bar", class-link: "/classes/1" } </code></pre> <p><strong>Response:</strong></p> <pre><code>201 Created Location: http://example.com/students/10 </code></pre> <p>Listing the collection of students (following the <code>students-with-classes</code> relation);</p> <p><strong>Request:</strong></p> <pre><code>GET /students?expand HTTP/1.1 </code></pre> <p><strong>Response:</strong></p> <pre><code>200 OK Content-Type: application/hal+json { "_links": { self: { href: "/students" } }, "_embedded": { "students": [ { "_links": { "self": { "href": "/students/1" }, "classes": [ { "href": "/classes/1", "title": "A" } ] }, "name": "Foo1", "surname": "Bar" }, { "_links": { "self": { "href": "/students/2" }, "classes": [ { "href": "/classes/1", "title": "A" } ] }, "name": "Foo2", "surname": "Bar" }, { "_links": { "self": { "href": "/students/3" }, "classes": [ { "href": "/classes/2", "title": "B" } ] }, "name": "Foo3", "surname": "Bar" } ], "classes": [ { "_links": { "self": { "href": "/classes/1" } }, "name": "A", "subject": "Math" }, { "_links": { "self": { "href": "/classes/2" } }, "name": "A", "subject": "Science" } ] } } </code></pre> <p>A couple of things to note:</p> <ul> <li>I <code>POST</code> generic <code>application/json</code> data but retrieve <code>application/hal+json</code>. The representations do not need to be the same in each direction.</li> <li>I use the URI as the resource identifier for the Class to link to, not an artificial external ID. Such an ID <em>may</em> be part of a that URI, but the client should never make that assumption.</li> </ul>
    singulars
    1. This table or related slice is empty.
    plurals
    1. This table or related slice is empty.
    1. This table or related slice is empty.
    1. This table or related slice is empty.
    1. This table or related slice is empty.
    1. This table or related slice is empty.
    1. This table or related slice is empty.
 

Querying!

 
Guidance

SQuiL has stopped working due to an internal error.

If you are curious you may find further information in the browser console, which is accessible through the devtools (F12).

Reload