Use links not keys to represent relationships in APIs

Re:Use links not keys to represent relationships in APIs by dragonwriter on Sunday May 12, 2019 @05:07AM (#19890891)

> More fundamentally, I think it's trying to solve a smaller problem in the face of a much bigger one, you still need to know what the response of any given endpoint is going to be. Just because they've passed me a link, doesn't me I don't need documentation on what endpoint that link points to. I still need to know that the owner is a link to the people endpoint so I can properly parse that result.

Well, yes, you need to know the semantics of the relationship, but not for parsing, because he content-type plus, where needed, internal data within the resource representation more specifically identifying the subtype should tell you what you need to know about handling the representation.

That's HATEOAS.

[ Parent | on HN ]

Re:Use links not keys to represent relationships in APIs by statictype on Sunday May 12, 2019 @08:54AM (#19891584)

You absolutely still need docs on the end point.

If you’re interacting with the api then it’s extremely likely you’re not going to write code that will automatically follow reference links and attempt to parse them dynamically.

You will need to know what fields are in the end point how they represent data (iso 8601 for dates? Unix timestamps?).

You’re substituting documentation with asking the api consumer to explore and discover and assume.

[ Parent | on HN ]

Re:Use links not keys to represent relationships in APIs by M2Ys4U on Sunday May 12, 2019 @06:28PM (#19894998)

You need docs about the media type, which is not exactly the same thing.

But you've documented how your API works anyway, right?

[ Parent | on HN ]