2

I am tasked with designing an API for a car registration service. I don't have all the details yet, but we will receive requests from car dealers via API that my client will then process and forward to the government agency. It's a service to reduce bureaucratic workload for the car dealers.

Those dealers are all using different software to enter car owner data etc. The idea is that those software providers will then create some sort of module to connect to our API.

To me this sounds like a receipe for a lot of headaches. But it also sounds like we might benefit from some sort of API standard, which might be REST?

Both my client and the car dealers are located in the same area. So me could interview them about what their client software might require, if that is of any advantage to the project.

I have implemented a few REST APIs in several projects and the need for support was always rather high, ie. request bodies were not documented in every detail, responses would contain cryptic data sets, custom features or resource properties were needed etc.

What pitfalls would we have to avoid in order to reduce support for API client developers to a minimum in this scenario? Can a question this broad even be answered?

EDIT: replaced "communication" with "support"

9
  • Will their clients conform to your API? If so, design an API that doesn't need a lot of back and forth (transmit larger DTOs rather than small "entities"). <-- EDIT: I've written this assuming you meant network communication - but, did you mean communication between people instead (as in, about project organization & logistics)? Dec 1, 2021 at 14:25
  • Can you clarify what you mean by communication in this context? Do you mean the need to have conversations between the maintainers of the API with the people who will make requests to it? Do you mean the number of HTTP requests sent to your API? Dec 1, 2021 at 14:27
  • 1
    Well, while there might be a way to design away some of that, ultimately, that is less of an API design problem, and more of a business problem. Dec 1, 2021 at 14:36
  • 1
    So the car dealers need to invest a lot of money to make their software vendors adapt their software to your API? Why should they? Is there a legal obligation for them? Besides that, I think you should not talk to the car dealers, you should talk to their software vendors instead.
    – Doc Brown
    Dec 1, 2021 at 14:48
  • 3
    It seems to me that your answer is somewhere in here: "request bodies were not documented in every detail, responses would contain cryptic data sets, custom features or resource properties were needed etc."
    – JimmyJames
    Dec 1, 2021 at 15:55

2 Answers 2

5

If you are designing an API that someone else will use, the way to avoid support would be to provide good documentation, a test environment, and a example implementation.

This would somewhat depend on how complex the API is, a very simple REST API might just be described as an url with a <INSERT_X_HERE> placeholder. The more complex it is, the more documentation and help will be required.

High level documentation

A high level description is often useful to provide a better understanding of the purpose and requirements of the API.

Schemas

When using something like a REST API it is very useful to have all the relevant schemas, and endpoint signatures. Preferably automatically generated to ensure it is up to date.

Test environment

They will need some way to test their code without actually breaking anything, so some kind of test server would be needed, either something running locally, or online.

Example implementation

An example implementation, including source code, is a good way to test that you have setup your test environment correctly, and that there are no firewalls or other issues. It is also helpful as a way to review that the API is used correctly.

If all of this is provided in a clear way using common tools, I think most competent developers would succeed in using the API. The problems I have experienced have either been poor documentation, or related to fundamental requirements, like allowing internet access.

1
  • 1
    The only thing missing in this answer is to use an industry standard schema for your API, at least one almost definitely exists.
    – Ryathal
    Dec 2, 2021 at 13:19
2

Sure, documenting helps, but is not the main problem usually. It is burdening the client with irrelevant stuff (like what HTTP methods, what URIs to use, etc.), and completely forgetting important stuff (like in what order to call, what is the workflow itself, etc.)

This is of course just one point among dozens, but this is what I would do (if you get to the implementation part):

  1. Try to design a really good web application. For people. Like authentication, wizards to enter stuff, search makes/models, whatever the process is to register. Make it work for people.
  2. Add a json-based (or whatever format-based) equivalent to all the HTML pages. Including everything, forms, links, hidden fields, etc.
  3. You're done.

There are of course other, finer points I left out, but this would reduce the knowledge clients have to worry about a lot, less documentation necessary, a working example already there in HTML that everybody understands. Probably a lot less support needed for this, than for a data-based request-response type API without any context.

Again, this is just the technical side, you'll probably have other headaches as well. :)

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

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