How Do I Design APIs for Longevity and Stability?

If the contract changes, you'll want a new version. It's also a good practice to use Data Transfer Objects (DTOs) to separate your API's request and response structures from your internal models. Additionally, if you're using OpenAPI SDK, you can mark endpoints as obsolete to warn clients that they're still available but may eventually be removed.

This is a pretty open-ended question! Do you have any specific examples? Generally speaking, versioning your API is essential. You want to make sure you don't disrupt current users when making changes.

Implementing versioning like /api/v1/ and /api/v2/ is standard, but I've rarely worked with more than two or three versions at a time. A good API design right from the start is crucial. Make sure you carefully determine what you want to expose and in what format. New versions should be thoughtful changes rather than fixes for mistakes; it's better to ensure stability from the beginning.

The key to preventing issues with your API is to avoid changing the interface itself. Keeping the existing interface stable is critical.

You can version your API by using a header value in the request. This is often more practical, especially if you know your users have saved the href, so you won't disrupt them. However, this does mean you're responsible for managing that header and ensuring it routes requests to the right version.