web services - REST JSON specification -

i'm newbie both in soap , rest programming.

• in soap structure , fields of entities being exchanged , unambiguously documented in wsdl.

• i think same not happen in rest.

how developer of rest api supposed document structure , fields of json objects, representing entities being exchanged?

rest , soap can't compared directly, different things. can implement rest on soap if want, not opposite. recommend reading this answer.

in restful apis supposed document media-types , let interaction driven underlying protocol, don't in of http apis call rest. using term buzzword , opposite of that, documenting protocol instead of media-types.

for instance, if have user resource, supposed have proper media-type in format json or xml looks application/vnd.mycompany.user.v1+json, , documentation should describe json document looks client knows expect. doesn't have strict wsdl. in fact, can human readable documentation documenting class api or that.

the client can media-types prepared accept accept header. instance, if client wants v1 representation in json, can use like:

get /users/xyz accept: application/vnd.mycompany.user.v1+json 

if wants v2 representation in xml, can use like:

get /users/xyz accept: application/vnd.mycompany.user.v2+xml 

and if wants json , let server decide do, can use generic media-type , figure out server threw @ him checking content-type response header.

get /users/xyz accept: application/json 

however, keep in mind of called rest apis you'll find don't use custom media-types this. instead, use same generic media-types application/json , application/xml everywhere. means clients have identify resources through uri semantics , relations, , that's not rest @ all. i'm not saying it's wrong, it's simple , works many problems, it's not rest , doesn't solve same kind of problems rest intends solve.