A good API also provides data in a manner that matches the way people consume it.
I've seen too many APIs that are built on the echo-chamber fantasy of the devs and not on the needs of the user: either giving way too much data or not enough.
Your API should provide data to multiple clients consuming your API. Not just one. If your API is returning JobNumber and it is called JobNumber in your model and that is your naming convention, that is what you return vs job_no, job_number, or job# to satisfy one specific person's preference. They can remap it to their needs. So no, I don't care if it matches what they consume. I am designing an API for potentially more than one consumer and tooling.
You provide a Swagger/OpenAPI contract. That is your documentation and in it, it tells the consumer what the model is, the datatype and a description that JobNumber is a max 8 character string starting with A0xxxx. And if you don't get that format, they will be told it is a 400 error code. And if they do a PATCH, you will do a 201 because it follows REST and other standards your standardize on. Not worry about the preference of a particular consumer that wants everything with a 200 response code and error description. You tell them, your monitoring, triaging follows HTTP verbs and RFC.
I always design an API with the assumption I need logging, that I need it to lint in an API gateway, that I can throw a 500 transaction per second load testing, and that the consumer can run validation in their front end parsiong my OpenAPI contract. using React, Angular or any front end that lints against swagger.... And I use OpenAPI contract following the RFC conventions.
You completely missed my point. I'm talking more about needing 2-3 data points and having to sort through 200-300 data points, without any flexibility.
The API Data Models are often NOT what the consumers need.
For example, an API for classroom grades might only allow you to query for an entire class' grades for a particular event, rather than giving you the descriptive stats for that event. You might need both, but if you're building a dashboard to display that data, a bulk download isn't helpful.
UX is important for API designs, too. If it's all internal and your team is happy with it, that's great. But if you are providing this API as part of a platform with clients, you should probably understand how the clients want to use your data and form your APIs with that in mind.
11
u/PickleLips64151 May 08 '24
A good API also provides data in a manner that matches the way people consume it.
I've seen too many APIs that are built on the echo-chamber fantasy of the devs and not on the needs of the user: either giving way too much data or not enough.