Why shouldn't you design APIs using ad hoc JSON?

[Martin Bayly]

In the book RESTful Web APIs, the authors (Mike A?) make the following statement when discussing "Semantic Descriptors" in Chapter 8 - Profiles - Profiles Describe Application Semantics

<snip>

In ad hoc JSON—not just in the documents served by the Twitter API—it’s customary to use semantic descriptors as object keys:

{"name" : "Jenny Gallegos"}

(JSON-LD, which I’ll cover in an upcoming section, is based on this convention.)

Similarly, in ad hoc XML documents, the tag names often correspond to semantic descriptors:

<person>
 <name>Jenny Gallegos</name>
</person>

But those last two are only conventions. Clients can’t rely on them in general. That’s one reason I don’t think you should design APIs using ad hoc JSON or XML.

</snip>

Can anyone comment on what the authors mean by "conventions"  Also, when they say they don't think you should design APIs using ad hoc JSON, do they mean they don't think you should include complicated JSON representations of entities with lots of nesting etc?  Instead, they are saying they prefer a more generalized approach like the name/value pairs in Collection+JSON, or the property groups of Siren? (Which as I understand it can have complex JSON objects as values, but anyway...?)?

Thanks for any clarifications/interpretations anyone can provide.

Martin

[mca]

One of the points we were making in the book was that adHoc designs will need adHoc client solutions.  IOW, each time you design a unique message format, you need to write a new client.

So, yes, we encourage the use of formats (and idioms) that reduce the amount of customization needed for a client to interact w/ a service. 

hope that helps.

Cheers.

mca

Mike Amundsen

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

--
You received this message because you are subscribed to the Google Groups "Hypermedia Web" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hypermedia-we...@googlegroups.com.
To post to this group, send email to hyperme...@googlegroups.com.
Visit this group at https://groups.google.com/group/hypermedia-web.
For more options, visit https://groups.google.com/d/optout.

[Martin Bayly]

Thanks, yes, that helps.  I've also been ploughing through many of the posts on API Craft and that has helped me understand your perspective more.

e.g.

https://groups.google.com/d/topic/api-craft/ZxnLD6q6w7w/discussion

https://groups.google.com/d/topic/api-craft/NgjzQYVOE4s/discussion

Cheers

Martin

[Alex Moore - Niemi]

one place i've had a lot of trouble with this is where the API has to provide for mobile clients, because we just don't have a generic representation of their native abilities.