Naming

Use the vocabulary of your audience when naming API resources and attributes.¹

If the set of actions a user can take on a resource is large, split it into multiple resources.

the set of actions you can take on an originated ACH transfer is different (the complete opposite, really) than the actions you can take on a received ACH transfer, so we separate these into ach_transfer and inbound_ach_transfer resources.

... considering the level of abstraction that’s appropriate for the developers integrating against it is a valuable exercise.¹

Immutable APIs

The use of immutable objects helps create an API model that fits in your head.

we try to model our resources after real-world events like an action taken or a message sent. This results in more of our API resources being immutable.¹

References

¹ Increase, No Abstractions: an Increase API design principle, Version 2024-04-30, [Online]