9 thoughts on “An Overview of REST Metadata Formats

  1. Jason Harmon

    This is one of those perspectives that reminds us we are just at the edge of a new frontier. The liberty of choice is presenting us with so many options that the best is not yet clear. While standards helped drive the SOA adoption in the SOAP era, our lack of standards is driving more innovation. I like that you touched on meta as a topic, but I’m sure some folks will take issue with referring to Hypermedia links as meta (versus being a direct aspect of the content).
    Great stuff!

    Reply
  2. Pingback: An Overview of REST Metadata Formats | Next Web...

  3. Ole Lensmar Post author

    Hi Jason,

    Thanks for this! Regarding if links/actions are metadata or not – perhaps there is an academic distinction as you say, but personally I find that describing and providing available actions for a resource inline (as part of the response) or externally (for example in a swagger definition) is still the same “metadata” and there are pros and cons for each approach (maybe that would be a good follow-up post!?) – once again knowing your end users and how they will want to consume your API is crucial to making the right choice.

    cheers!

    /Ole

    Reply
  4. Pingback: Scott Banwart's Blog › Distributed Weekly 202

  5. Mike Amundsen (@mamund)

    Another way to view this space is to think about the differences between
    – a Service document approach (WSDL/WADL, etc),
    – a Discovery document approach (JSON-LD/Hydra, Nottingham’s JSON Home documents, Google’s Python library, etc.)
    – a Hypermedia approach (Collection JSON, HAL, Siren, etc.).

    While they all attempt to expose metadata about a service or API, they not only do this in different ways, but rely on different optimizations. Service docs optimize the build experience (via proxy generation). Discovery documents optimize the runtime via configurability; essentially Discovery documents are consumed by a static runtime client. Both of these approaches favor “knowing” the entire set of possibilities are design/build-time.

    Hypermedia is a runtime optimization based on _not_ knowing the entire set of possibilities. Hypermedia metadata is served up on an “as needed” basis – a very diff approach and one that continues to vex those attempting to create documentation for APIs.

    Reply
  6. Pingback: Data Modeling for APIs. Part 2: REST and JSON | Linked Data Orchestration

Leave a Reply