Good API:
- Fast
- Good match of data required to data returned: In other words, API responses contain enough data to meet the needs of the app, and very little extraneous
- Response shapes:
- Nesting is limited
- Data needs little manual normalization on client side
- Useful, ideally machine-parsable, errors
- Consistent representation: Entities/objects should be consistent in terms of naming, data types, structure, etc. from endpoint to endpoint
Bad APIs:
- Slow
- Bloated over time: APIs that are poorly maintained tend to have response sizes that grow over time. It's easy to add data to an API response. Removing data is much harder, because it's not clear what data is being used by what app and under what circumstance.
- No size fits all: Often APIs will have some endpoints that return a very limited amount of data, and some that return a lot of data. The needs of the UI may require data that isn't present in the smaller response, so the larger one is used instead even though most of the data returned by that is ignored.
- Forced serial requests: This is more subtle, but pernicious. In situations where the UI should call two endpoints to get the data it needs, poor architecture can lead to a situation where data from the first response is necessary to create the request for the second response, which means the two requests can't be dispatched in paralell, they must be in serial. Sometimes this is unavoidable, but where it can be avoided, it should.
The Normalization Shuffle: (I don't know what to do about this, but it strikes me as strange) Data is normalized in DB SQL query denormalizes data ORM re-normalizes some of the data JSON serialization de-normalizes some of the data Client code re-normalizes data If Client updates data, it may de-re-normalize data to make PUT request, which is re-de-re-normalized by API code to merge with semi re-normalized data in ORM to craft SQL queries against normalized data