Say we have a company that provides services and they would like to build a new API to sell to clients who will use it for their websites. Some things to consider:

  • The company has an old API that the company was able to sell to clients, however, the API was not designed very well and it is outdated and so it is hard to develop. This is why they are considering building a new one.

  • The company doesn't have any current clients for the new API so they don't know all the requirements for it.

My question is, what would be some good practices for designing an API when we don't know most of the requirements for it?

  • 8
    I'd write an answer, but I don't know most of its contents yet. – Flater Jan 19 at 19:45
  • 2
    @Flater: Just start writing an answer, and then we can build on it over and over and over and over and over and over and over and over again until rhoward likes what it says. Agile answering, I call it! – Greg Burghardt Jan 19 at 19:47
  • Surely the requirements are whatever the clients of the old API do with the old API? – user253751 Jan 19 at 19:54
  • @user253751 Let's say that the clients of the old and outdated API only use a small subset of the services. – rhoward Jan 19 at 20:05
  • 1
    API worsioning? – rwong Jan 19 at 20:22

There is no general best practice here.

Before designing the new API, you need to analyze the old API to determine its downfalls. "The Big Rewrite," which you are proposing, should be justified in order to make the clients' lives easier, or your own. Better yet it should make the clients' lives easier, maintenance and extensibility easier for you, and make the company money.

First identify the reasons. Then identify the use cases. Don't build anymore than you absolutely need to. Engage your clients in the very beginning so they can help guide the public interface for this service.

Agile development was created in part to address these sorts of situations. We need to build something, but we don't know the final product — no big deal. Talk to your customers first, and see what they need. Talk to developers, cyber security, testers and operations folks to see what they need. Ask the product side what their "vision" is (they should have one). Start work as early as possible and build iteratively. Once you have a complete enough feature set, put it out there for your clients to use.

  • While we are at it (often forgotten): ask the project lead about the business value, and how many licenses they want to sell to which customers for which amount of money. – mtj Jan 19 at 19:54
  • And maybe you should base your new API on the old one updating it bit by bit instead of creating a new one. Sometimes this is much better than a full rewrite. – f222 Jan 20 at 8:16

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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