With Frends API you can follow the best practices of Rest APIs when it comes to naming the endpoints. As in Restful way HTTP methods should not be used in the endpoints. For example /api/sample/getbooks can already be defined with the Get method so there's no need to define what the endpoint is for in the name the Get method does that already. So a better solution for the endpoint would be /api/sample/books.

When developing API endpoints you should always prefer plural naming conventions e.g. /books instead of /book. This will make it more understandable for the end users and developers. You are usually fetching a single book from list/catalog of books so this is more defining naming convention.
​

Resource nesting can make your APIs more efficient and easier to use. For example /books/lord-of-the-rings/parts/fellowship-of-the-ring can minimize the overhead of fetching the resource when the filtering is done already in the endpoint level.

One of the most valuable best practice is to keep your endpoints easy to read and work with. This will make the end users, integration developers and system analytics happier and make the development more efficient and simpler.

When developing APIs one best practice concerns the versioning of the API. In the API specification you can determine the version number of the API in it's own property field and Frends will automatically increase the build number when a new version is deployed to an Agent Group.
​

However usually API's base URL includes the API version number as well e.g. /api/sample/v1. Here you can see the version number 'v1' a.k.a version one. Modifying this is a bit more trickier because the base URL is unchangeable after you have first time saved the API specification. To increase this version number you need create a new API specification and copy paste the contents of the previous version to it and change the base URL before saving the specification.

Usually the path version number needs to be change only in those situations where the API changes drastically with some breaking changes. Therefore this usually needs to be done only in certain situations and not that often.

The next article is Introduction to API Specification How to use Swagger Editor.