saml/article hal rest.md

## article hal rest.md

      
    Raw
  

              article hal rest.md
            
          
    Example article API.

An article can have one main image. And many secondary images.
GET /articles/1

{
  "_links": {
    "self": {"href": "/articles/1"},
    "image": {
      "href": "/images/a.jpg",
      "width": 1000,
      "height": 2000,
      "credit": "Getty Images"
    },
    "image:secondary": [{
      "href": "/images/b.jpg",
      "width": 500,
      "height": 500,
      "credit": "Getty Images"
    }, {
      "href": "/images/c.jpg",
      "width": 1000,
      "height": 700,
      "credit": "Creative Commons"
    }]
  },
  "title": "abc",
  "html": "<p>hello <img src=\"/images/a.jpg\"></p><p><img src=\"/images/b.jpg\"><img src=\"/images/c.jpg\"></p>"
}

To
/articles/1 has links to self and image.
Representation is representation (of a resource, which is abstract).
_links and _embedded are auxiliary. Not really part of /articles/1 in a way.
You can PUT like the following in an attempt to modify linked image resource:
GET /articles/1

{
  "_links": {
    "self": {"href": "/articles/1"},
    "image": {"href": "/images/a.jpg"}
  },
  "_embedded": {
    "image": {
      "_links": {
        "self": {"href": "/images/a.jpg"}
      },
      "credit": "Flickr"
    }
  },
  "title": "abc",
  "html": "<p>hello</p>"
}

But server ignores _links and _embedded. So, above PUT request is same as:
PUT /articles/1

{
  "title": "abc",
  "html": "<p>hello</p>"
}

If you actually want to modify the image, you should follow the link (doc._embedded.image._links.self.href).
GET /images/a.jpg

{
  "_links": {
    "self": {"href": "/images/a.jpg"}
  },
  "credit": "Getty Images"
}

PUT /images/a.jpg

{
  "credit": "Flickr"
}

# responds with

{
  "_links": {
    "self": {"href": "/images/a.jpg"}
  },
  "credit": "Flickr"
}