How to design a wrapper for a large, multi-response API?

Question

Lets say there exist some service at some organization that exposes information on a company's assets, from employees, company-issued devices (laptops and issues) to the the large xerox printers on each floor and the large servers in the many different server rooms. Each of these objects (laptops, enterprise printers, servers) have their own set of attributes.

ex. /api/v1/assets

This service is standing in front of many different asset management databases. You basically send this large JSON object to ask for what you want, whether it be information on users personal laptops or information on servers.

A request may look something like this:

{ "asset_type" : "laptop", "attributes" : ["assignee", "os", "physical_address", "manufacturer"]}

A response will look something like this:

[{"assignee" : "238947", "os":"Win7Prem", "physical_address" : "3C:BF:12:90:0A:X2", "manufacturer":"Dell"}

And just imagine that each of these objects had 20-30+ attributes and with each request you could pass a filterList that allows you filter the responses based on the values of one or more attributes. For example, pulling all laptops where Manufacturer="Dell".

How would you design an API wrapper for this to be used in another application?

Would you just keep these pre-built queries in a file on the server and grab them when you need to? Maybe a seperate server for queries and then just make the API calls?

OR...

Would you write an AssetsAPI class and create methods? How would you organize your calls? Keep track of queries and attributes? Would you create classes for each of the asset types?

Let me mention that the asset data is being called from the app, going through some enrichment process, and then served from the calling API as another API response

• svidgen: What API's have you used that were pleasant to use? What API's have you used that were unpleasant? Can you describe them? ... If you have zero exposure to good API's, go find some API's and try to use them. Model your API after the ones that were easy to get started with and also easy to do more complicated things with. Take note of things that were difficult to code against.

Answer 1

As always^*, you want your domain model to drive these decisions.

Whether you need specific asset classes (Printer, Laptop) or just a general Asset class depends on what your 'enrichment' process is doing. Regardless, your domain logic should be separated from the details of the web API by some abstract interface.

interface Assets
{
 Printer getPrinterByName(string name);
 Laptop getLaptopByAddress(MacAddress address);
 // etc.
}

The class that implements the Assets interface can perform the requests in whatever way is most convenient and maintainable for you.

• If you just have a couple of pre-defined queries that you'll run all the time, loading them from a file - or defining them as constants in your code directly - may be a fine approach.

• If you have to execute highly customized queries, it's probably better to assemble them as needed.

• If your queries are complex, it may be worthwhile to split the implementation up even further into

  • an AssetsWebAPI class that closely reflects your web API and takes parameters such as assetType and attributes and
  • a higher level class that implements the Assets interface, provides the relevant parameters to AssetsWebAPI and turns the response into a Printer, Laptop, etc.

Try to choose the simplest approach that works for your application, but do refactor when things start to get messy.

_{* except sometimes}

Answer 2

Would GraphQL be a way forward?

https://graphql.org/