API design: how to minimize client support?

Question

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"

Answer 1

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.

Answer 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. :)