This question is in the context of web based applications. A web server exposing an HTTP api for clients (e.g. running in a browser but not necessarily). Usually the web server would be connected to somekind of datastorage.
My concern is the API exposed by the HTTP server, and how to design it.
I find that, often, a big part of api exposed to the client is just a CRUD interface to the datastorage. For example, the api almost always contains things like:
- get_all_users()
- get_this_user(id)
- create_new_user(name, email, phone, password)
- update_user(id, name?, email?, phone?, password?)
- delete_user(id)
This is not all the API does, but it something that is common to a lot of APIs I've worked with.
Depending on what the client needs, I often end up with more and more things in the API such as these:
- get_user_by_email(email)
- get_all_users_along_with_number_of_lincenses_for_each()
- delete_all_these_users_at_once(array [])
- get_users_whose_profile_is(profile_name)
- get_names_of_users_who_are_admin_profiles()
- .... etc
In other words, the client often needs to do joins, filter, and sort the data in all kinds of ways.
Which has led me to overly bloated APIs (just like the one above) supporting all kinds of options for filtering, sorting, and joining with data from other tables.
The resulting API is too complex for both the client to use and learn and for the server to maintain and test.
(IMO the Zabbix HTTP api suffers from this syndrom).
Questions:
Do you have similar experience?
Do you have some pointers as to how to strike a good balance between API completeness and complexity.
PS. I'm aware of REST, but I don't find it resolves the problem, the api provided is still very basic, and doesn't solve the get_users_along_with_number_of_licenses() or the get_names_of_users_which_are_admin() api calls.;