Oh certainly. It’s pretty rare to get things exactly right on the first try. For this reason we hide new endpoints from our public open api spec and documentation until we are satisfied that some dust has settled on them a little bit.
Still you only have to get it mostly right. Enough to get started. This only starts to become a huge problem when the endpoints is a dependency of another team. When you’re in constant communication between the developer building the API and the developer building the client it’s easy to adjust as you go.
I find a key part of a workflow like this though especially if you have multiple teams is to have a lead/architect/staff developer or whatever you may call it be the product owner of the API.
You need someone ensure consistency and norms and when you have an API covering functionally as broad and deep as the one I work on, it’s important to keep in mind each user story of the API:
- The in house client using the API. This generally means some mechanism to join or expand related records efficiently and easily and APIs providing a clear abstraction over multiple different database table when necessary.
- The external client, used by a third party or the customer directly for automation or custom workflows. The biggest thing I’ve found helps these use cases is to be able to query records by a related field. For example if you have some endpoint that allows querying by a userID, being able to also query by by a name or foreignID passed over SSO can help immensely.
Still you only have to get it mostly right. Enough to get started. This only starts to become a huge problem when the endpoints is a dependency of another team. When you’re in constant communication between the developer building the API and the developer building the client it’s easy to adjust as you go.
I find a key part of a workflow like this though especially if you have multiple teams is to have a lead/architect/staff developer or whatever you may call it be the product owner of the API.
You need someone ensure consistency and norms and when you have an API covering functionally as broad and deep as the one I work on, it’s important to keep in mind each user story of the API:
- The in house client using the API. This generally means some mechanism to join or expand related records efficiently and easily and APIs providing a clear abstraction over multiple different database table when necessary. - The external client, used by a third party or the customer directly for automation or custom workflows. The biggest thing I’ve found helps these use cases is to be able to query records by a related field. For example if you have some endpoint that allows querying by a userID, being able to also query by by a name or foreignID passed over SSO can help immensely.