json - Updating resources in RESTful API with forms or representations -

json - Updating resources in RESTful API with forms or representations -

i saw many examples xhtml used in restful api authorization oauth or openid. while seems quite natural asked myself if there other advantages submitting forms improve posting/puting representation of resource ? i'm interested in machine-to-machune interaction human-to-machine.

if understand well, 1 of aspects content-negotiation xhtml forms can returned client or not (because default json , xml doesn't back upwards forms) depending on accept header in request.

let's have simple scenario item resource added cart resource. api supports json , xml. i'm doing want client post item resource representation cart resource , works great. client should aware of semantics , need know construction of item resource representation because otherwise encounter error 400 (bad request).

then thought using forms easier as provide guidance client on post cart. there problem, because supported ootb xhtml illustration not json or xml (unless using collection-json etc.). provide custom implementation in order back upwards forms in json , xml require client understand semantics , there no gain in using forms on posting resource representation.

question : please clarify if there scenarios forms should used, or usage preferable on posting resource representation ? there official guidance ?

question 2 : bother using forms in xhtml format communication between api , clients in json or xml, or modify xml/json in order contain custom forms ?

maybe i'm missing that, don't hesitate set me on right tracks :)

if want add together item cart, there 2 options.

1. cart part of rest client's state, not store info in rest service. in case can store items , amounts on client side or in cookie, or in server side rest client, not matter. should store url of items, id of items, , amount, , maybe cost too... of these come rest service...

2. cart stored in rest service, resource, , alter of has effect on resource states of service. in case can create cart post /carts request, after unique cart id:

201 { id: 123, _links: { self: {href: "/carts/123"} } }

your client has remember that, if link template catalog, illustration /items?search=@keywords&cart=@cart.id, can fill cart id on that...

by browsing catalog can items way: get /items?search="red pullover"&cart=123. after add-cart link item:

{ id: 567, name: "red pullover", _links: { "add-cart": { href: "/cart-items", fields: { cart: {type: "hidden", value: 123}, item: {type: "hidden", value: 567}, amount: {type: "select", value: 1, min: 1, max: 10} } } } }

you can create form , button link if session.cart.id exists in client. if not can ignore link. if pressing button in generated form, send service:

post /cart-items { cart: 123, item: 567, amount: 1 } 201 { id: 22222, _links: { self: {href: "/cart-items/22222"} } }

so if want service remain restful, client must never generate links. gets links service. service never stores client state, client state comes in querystring or postdata...

you can send response in html rest client, , rest client decides response, , how display it. improve send responses in info format, illustration hal+json or json-ld or atom+xml, because have existing serializers , unserializers. html not have serializer/unserializer, slow parser, if utilize html have write part of code yourself.

you can find out own form representation illustration hal+json, or can utilize existing schemas. json-ld , atom+xml , hal+html can bound existing rdf schemas or maybe microformats, maybe there schema how describe forms. can browse existing schemas illustration on schema.org, or can find existing link relations here: link-relations. there many other solutions everything, not displaying forms, representing data. can find out more keywords: linked data, linked open data, etc...

json rest xhtml