Examples on hyper schema?

[Ning]

Hi,

  Are there some examples on the links?

  I have a very basic question. I think I got myself confused. Is it true that some links should exist for a singular resource, some should exist for collection resource?

  Say I have a collection resource under /books. GET /books return all the books, and GET /books/xyz returns one book with a title "xyz". For example:

GET /books returns:

{

  "books": [

    {"title": xyz, "author": "foo", "linksForMyInstance": [...]},

    {"title": abc, "author": "bar", "linksForMyInstance": [...]},

    {"title": 123, "author": "foo", "linksForMyInstance": [...]}    

  ],

  "linksForMyCollection": [

    ......

  ],

  "_context": {

    "count": 3...

  }

}

GET /books/xyz returns:

    {"title": xyz, "author": "foo", "linksForMyInstance": [...]}

  I could have a schema for /books resource like this:

{

  "type": "object",

  "properties": {

    "books":{

      "type": "array",

      "items": {

        "properties": {

          "title": {...},

          "author": {...},

          "linksForMyInstance": {...}

        },

        "links":[

          {"rel": "self", "href": "{title}"},

          {"rel": "instances", "href": "/books"}

        ]

      }

    },

    "linksForMyCollection": {

      ......

    },

    "_context": {

      ....

    }

  },

  "links":[

    {"rel": "self", "href": "/"},

    {"rel": "instances", "href": "/books"}

  ]

}

  Does the "instances" link in the inner links section make sense?

  What should be the self link in the outer links section?

  Thanks.

Ning

[Philippe Marsteau]

Ning, I guess you meant: 

 "links":[

          {"rel": "self", "href": "/books/{title}"},

          {"rel": "instances", "href": "/books"}

        ]

in the inner section.

Looking forward the answer ;-)

[Geraint (David)]

On Friday, February 1, 2013 11:21:46 PM UTC, Ning wrote:

Hi,

  Are there some examples on the links?

There isn't a walkthrough for it yet, but I'm working on that.
 

  I have a very basic question. I think I got myself confused. Is it true that some links should exist for a singular resource, some should exist for collection resource?

Yes - for example, a "create" link to post a new item should apply to the collection.  However, an "author" link should apply to the individual resources.
 

I'm slightly confused - what were you intending to place inside "linksForMyCollection"?  LDOs?  Just URIs?

  Does the "instances" link in the inner links section make sense?

I think "parent" would be more appropriate.
 

  What should be the self link in the outer links section?

The link applies to the instance that the schema describes.  In this case, that schema is describing the data at "/books", so the self link should probably be "/books".
 

  Thanks.

Ning

[Ning]

David,

  Thanks for the help.

  LDOs will be placed inside the linksForMyCollection or linksForMyInstances. They are just links in the json instances, for whatever reason that need to exist in the instance rather than in the schema.

  In my example, both /books and books/xyz are returning a singular resource. /books does contain an array, but since it has other properties, the array is only one property. In this case, the "instances" or "create" link don't seem to make sense in either of them. Is my understanding correct?

  So the inner link (at /books/xyz level) is something like:

"links":[

          {"rel": "self", "href": "{title}"},

          {"rel": "author", "href": "/authors/{author}"}

        ]

  and the outer link (at /books level) is:

  "links":[

    {"rel": "self", "href": "/"},

  ]

   Thanks.

Ning

[Philippe Marsteau]

"instances" in /books/xyz level does make sense, since it instructs a user who performed a GET on this path, that it can reach the parent (collection) resource following the "instances" link. You may rename "instances" for "parent" if this makes more sense to you.

[Philippe Marsteau]

Actually it seems "parent" isn't officially IANA standardized. Use "up" if you want a registered IANA relation type.