Real world example for webservice w. restful resources

[Schorsch]

I'm going to use json-schema to describe the webservice of
salesking.eu. Internally the schema is used to deliver outgoing and to
(partially)validate incoming data. The service is/tries to be restful,
but there are still some things to be implemented(header schema links,
cache,..)

So far it has been a pleasant experience but now i need some feedback
if i am on the right track,

Schemas can be found at https://github.com/salesking/sk_api_schema/blob/master/json/v1.0/

Some open questions:

Link-related: see https://github.com/salesking/sk_api_schema/blob/master/json/v1.0/invoice.json

href:
For now i prefix all links with the resources plural name or should i
use the root or pathStart element, and if where to put it(in the main
object?)? To me explicit link paths are not that bad and are easier to
read.

Nested link params:
To filter instances there is a param named "filter", which is an
hash=>

"filter[tags]":{
"Title" : "Tags",
"description": "Filter by a space delimited list of tags"
},
or should this be written nested like:

"filter":{
"Title" : "Filter",
properites:{
tags: { title: "tags"}
}},


POST/PUT params:
Is such valid?

"rel": "update",
"href": "invoices/{id}",
"method": "PUT",
"properties" : {
"invoice" : {"$ref":"./invoice.json#properties"}
}


Other issues:

Where or how would i describe an error object or return values for
links?

All listings(instances) will return not only the objects but also
information about the collection and links. Where would i describe
such? In a Collection object?

{
collection: {
total_entries: 38,
current_page: 1,
per_page: 30,
total_pages: 2
},
products: [
{
product: {
number: "P-2009-003",...
}
}
],
links: {
self: "/api/products?page=1",
next: "/api/products?page=2",
prev: "/api/products?page=0"
}
}


Thanks for taking your time to give me some hints. I really think json-
schema is the way to go, as for now i have not found any blocker. But
i would appreciate some more examples in the specs.

[Kris Zyp]

On Nov 15, 5:48 am, Schorsch <killergeo...@googlemail.com> wrote:
> I'm going to use json-schema to describe the webservice of
> salesking.eu. Internally the schema is used to deliver outgoing and to
> (partially)validate incoming data. The service is/tries to be restful,
> but there are still some things to be implemented(header schema links,
> cache,..)
>
> So far it has been a pleasant experience but now i need some feedback
> if i am on the right track,
>

> Schemas can be found athttps://github.com/salesking/sk_api_schema/blob/master/json/v1.0/
>
> Some open questions:
>
> Link-related: seehttps://github.com/salesking/sk_api_schema/blob/master/json/v1.0/invo...

>
> href:
> For now i prefix all links with the resources plural name or should i
> use the root or pathStart element, and if where to put it(in the main
> object?)? To me explicit link paths are not that bad and are easier to
> read.

The href URLs is resolved relative to the instance document, so if the
URL of an instance doc is http://site.com/instance/3 and there is an
href to "instance/{id}" this would resolve to http://site.com/instance/instance{id}.

> Nested link params:
> To filter instances there is a param named "filter", which is an
> hash=>
>
> "filter[tags]":{
>           "Title" : "Tags",
>           "description": "Filter by a space delimited list of tags"
>         },
> or should this be written nested like:
>
> "filter":{
>     "Title" : "Filter",
>     properites:{
>       tags: { title: "tags"}
>     }},

Probably the former would be a better bet, I don't think there is well-
defined conversion from nested objects to x-www-url-encoded

>
> POST/PUT params:
> Is such valid?
>
> "rel": "update",
> "href": "invoices/{id}",
> "method": "PUT",
> "properties" : {
>   "invoice" : {"$ref":"./invoice.json#properties"}
>   }

It is valid, but I would discourage putting PUT and DELETE in
relations. These are a well-specified part of the HTTP/REST uniform
interface of the original resource. No relation is need to the
original resource to apply these methods.

>
> Other issues:
>
> Where or how would i describe an error object or return values for
> links?

With HTTP, errors are indicated by HTTP status codes. Other protocols
have their own error systems.
Kris