如何设计可扩展的静态/非静态API？

Question

I have an API 'x' which does a CRUD on 4 params today - a, b, c, d. Tomorrow if I have to support few more params in the same API, due to change in requirement, then what is the best way to handle it?

Should I go ahead and update my DB with the new params introduced and continue doing this everytime there is a change in the requirement?

One of my peers suggests that the API should accept a JSON Object which can accept any set of params and any set of key-value pairs. Every time I get a new set of key-value pair via this JSON, I update my params table with this value and then the requirement can change as and when they want.

I think that this will be very difficult to maintain across clients as the API will literally accept any key-value pair and hence one platform might debate on sending these key-value pairs in one format while the other would be willing to send it in another format. Also, it will be hard to put in validations and check on optional and mandatory params.

Any leads is appreciated

Answer 1

My answer has a bit of nuance, so beware.

I find that in practice we don't make that many changes to our API's, and when we do, we can often do it in a way where it's backwards compatible. This does mean we add optional fields.

If you control all clients, it's also fairly easy because you can just upgrade all of them so it's not really an issue.

It's harder when you make changes more often, or are doing more than just adding some properties, and it's 3rd parties connecting to you, you can easily upgrade them.

There's more than 1 way solve this, but my recommendation is the follow github's model.

For bigger breaking changes they change the Content-Type header. Currently the Content-Type for github requests is:

Accept: application/vnd.github.v3+json

Before they made a big breaking change it was:

Accept: application/vnd.github.v2+json

For experimental API's that are prone to change they use an experimental Content-Type :

Accept: application/vnd.github.mister-fantastic-preview+json

Generally this idea is preferred for restful design, but it's not the only solution.