5 ms·
How does one even write an API client against a REST API that only publishes the initial entry point? in particular, how should the client discover the resource
by curt15 2y ago
How does one even write an API client against a REST API that only publishes the initial entry point? in particular, how should the client discover the resources that can be manipulated by the API or the request/response models?
- AdieuToLogic 2y ago> How does one even write an API client against a REST API that only publishes the initial entry point? in particular, how should the client discover the resources that can be manipulated by the API or the request/response models? HAL[0] is very useful for this requirement IMHO. That in conjunction with defining contracts via RAML[1] I have found to be highly effective. 0 - https://datatracker.ietf.org/doc/html/draft-kelly-json-hal https://datatracker.ietf.org/doc/html/draft-kelly-json-hal 1 - https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/ https://github.com/raml-org/raml-spec/blob/master/versions/r...
- loudgas 2y agoYour Web browser is probably the best example. When you visit a Web site, your browser discovers resources and understands how it can interact with them.
- Thiez 2y agoIt certainly does not. Sure it can crawl links, but the browser doesn't understand the meaning of the pages, nor can it intelligently fill out forms. It is the user that can hopefully divine how to interact with the pages you serve their browser. Most APIs however are intended to be consumed by another service, not by a human manually interpreting the responses and picking the next action from a set of action links. HATEOS is mostly pointless.
- deathanatos 2y agoThe responses from prior requests give you URLs which form subsequent requests. For example, if I, GET <account URL> that might return the details of my account, which might include a list of links (URLs) to all subscriptions (or perhaps a URL to the entire collection) in the account. (Obviously you have to get the account URL in this example somewhere too, and usually you just keep tugging on the objects in whatever data model you're working with and there are a few natural, easy top-level URLs that might end up in a directory of sorts, if there's >1.) See ACME for an example; it's one of the few APIs I'd class as actually RESTful. https://datatracker.ietf.org/doc/html/rfc8555#section-7.1.1 https://datatracker.ietf.org/doc/html/rfc8555#section-7.1.1. Needing a single URL is beautiful, IMO, both configuration-wise and easily lets one put in alternate implementations, mocks, etc., and you're not guessing at URLs which I've had to do a few times with non-RESTful HTTP APIs. (Most recently being Google Cloud's…)
- pests 2y agoLook up HATEOS. The initial endpoint will you give you the next set of resources - maybe the user list and then the post list. Then as you navigate to say, the post list, it will have embedded pagination links. Once you have resource urls from this list you can post/put/delete as usual.
- recursivedoubts 2y agoyour browser is a client that works against RESTful entries points that only publish an initial entry point, such as https://news.ycombinator.com https://news.ycombinator.com from that point forward the client discovers resources (articles, etc) that can be manipulated (e.g. comments posted and updated) via hypermedia responses from the server in responses
- wstrange 2y agoThe browser is also driven by an advanced wetware AI system that knows which links to click on and how to interpret the results.
- recursivedoubts 2y agoyes: https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.h...