Reading books on REST architecture(especially O'Reilly) many times I came across the idea that one should attach data's description into link http header.

    Link: <http://example.com/contactmanagement/profile>; rel="profile"
    Date: Fri, 21 Dec 2017 06:47:25 GMT
    Content-Length: ??

Where profile is URI pointing into data description(profile). There are several profile formats:

  1. ALPS (https://en.wikipedia.org/wiki/Application-Level_Profile_Semantics_(ALPS))

  2. Microformats (https://en.wikipedia.org/wiki/Microformat)

  3. HAL (https://en.wikipedia.org/wiki/Hypertext_Application_Language)

It seems that profiles are mostly used in areas of academic researches right now rather then enterprise applications. I'm wondering does anyone use them?


While this kind of metadata is undeniably useful to a human or a magic self-discovering client, it suffers the same problem as HATEOAS...

Usually you are making millions of identical calls via clients that already know the data format, so including human-readable or machine-discoverable links and other metadata needlessly adds to your bandwidth consumption, which tends to cost real money.

| improve this answer | |
  • 2
    I would even go so far as to say that, contrary to the popular fashion, most clients don't even require a RESTful interface. They just need a decent JSON API. – Robert Harvey Aug 7 '18 at 20:37
  • What about scenario when you are building service consumed by independent clients? I mean services located in Internet (non enterprise). In that case API must be documented anyway - are they document it in profile formats? – nikita Aug 8 '18 at 6:36
  • I think swagger is widely used : swagger.io/solutions/api-documentation – Ewan Aug 8 '18 at 7:00

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.