How best to programmatically navigate the Github API?

Question

The GitHub API supports HATEOAS quite elegantly, so navigating it from a graphical REST client like Postman is intuitive and fast.

They don't list all possible permutations of the endpoints when requesting "/", my guess is they only list the top 'root' endpoints that get you started so that you can then use the responses to dig deeper down the graphs.

As we know, one of the benefits of navigating the graphs using the URLs from the responses is that if the URL structure changes, end users will always know where to go.

Now what if you are writing a framework that wraps an API such as this. If you wanted to return data from deep in the graph, would you navigate the URL structure like an end user would and make multiple requests as you go or would you bake the URLs into the code and request them directly?

I know GitHub provides direct URLs to most (all?) child data but in my API this doesn't exist.

Answer 1

If you wanted to return data from deep in the graph, would you navigate the URL structure like an end user would and make multiple requests as you go or would you bake the URLs into the code and request them directly?

That will depend on whether or not your emphasis is on flexibility or performance/simplicity.

If you want to fully embrace the HATEOAS model, you will navigate the tree every time. Potentially, your software might be able to automatically adjust to a change in the HATEOAS model, if it is smart enough to perform that discovery itself. It might even cache urls it discovers for later use.

If you want an emphasis on performance and simplicity, you'll create an Adapter that accesses the URLs of interest directly. If a change occurs in the API, you use HATEOAS to discover the change, and bake in new URLs.