API Versioning

IMPORTANT: Note that the API Versioning (discussed here) and API Documentation features are mutually exclusive, only one of these features should be enabled, and we strongly recommend that you use API Versioning.

API Versioning

As it relates to web services, API versioning provides a mechanism to ensure that consumers can continue to use older or deprecated versions of your API, even after things may have changed, perhaps significantly, in later versions of the API. With RESTful web services, the way that versioning is most often implemented is by building a version number (v1, v2, v3, etc.) directly into the URL path of the service.

The library that we use to help us implement API versioning also has the ability to automatically produce Swagger API documentation for the web service, and this behavior will be enabled by default.

We strongly recommend that API Versioning support be enabled for all Harmony Core services.

Enabling API Versioning

To enable the API versioning in your Harmony Core development environment, edit your code generation batch file (regen.bat) and activate the ENABLE_API_VERSIONING option by removing the rem statement from the beginning of the line, like this:

set ENABLE_API_VERSIONING=-define ENABLE_API_VERSIONING

Note: Do not enable this option at the same time as the ENABLE_SWAGGER_DOCS feature. These two features are mutually exclusive.

Generate the Code

Save your changes to the batch file and regenerate your code. On this occasion, you will not see any additional files being generated as a result of enabling this option, all of the changes are in the form of additional code being generated into existing source files. This additional code is discussed below.

What Changes

Enabling this option causes the following changes in the environment:

1. All code-generated web service controller classes are decorated with an ApiVersion attribute. Here is an example of the attribute being applied to a web controller named CustomersController:

   {ApiVersion("1")}
   {ODataRoutePrefix("Customers")}
   ;;; <summary>
   ;;; OData controller for Customers
   ;;; </summary>
   public partial class CustomersController extends ODataController
   
   

   The version number (1 in the example above) comes from the user-defined tokens file (UserDefvinedTokens.tkn):

   <API_VERSION>1</API_VERSION>
   

2. All code generated web service endpoint methods are decorated with a Produces attribute to indicate that the operation returns JSON data, and with one or more ProducesResponseType attributes to indicate the specific type of data as well as the possible status values that the method might return. Here is an example of those attributes being applied to an endpoint method named GetCustomer:

   {ODataRoute("(CustomerNumber={aCustomerNumber})")}
   {Produces("application/json")}
   {ProducesResponseType(^typeof(Customer),StatusCodes.Status200OK)}
   {ProducesResponseType(StatusCodes.Status404NotFound)}
   {EnableQuery(MaxExpansionDepth=4)}
   ;;; <summary>
   ;;; Get a single Customer by primary key.
   ;;; </summary>
   ;;; <param name="aCustomerNumber">Customer number</param>
   ;;; <returns>Returns a SingleResult indicating the status of the operation and containing any data that was returned.</returns>
   public method GetCustomer, @SingleResult<Customer>
   

3. Additional code is generated into the EdmBuilder class, causing it to declare the API version number to Entity Framework.

4. Additional code is generated into the Startup class to enable API versioning.

5. Additional code is generated into the self-hosting application, causing it to display the URL where runtime-generated Swagger documentation can be accessed:

   ;;-------------------------------------------------------------------------
   ;;Report the location of the API documentation
   
   Console.WriteLine("API documentation is available at https://localhost:8086/api-docs")
   
   

New Endpoint URLs

When you build and run your service you will notice that all of the endpoint URL's now include the current version of your API, currently v1. For example, the OData service document will now be at the URL:

https://localhost:8086/odata/v1

The OData metadata will be available at:

https://localhost:8086/odata/v1/$metadata

And all of your code generated endpoints will also include the version number in the URL. For example, in the sample data set, you will now find the all customers endpoint at:

https://localhost:8086/odata/v1/customers

Viewing API Documentation

As mentioned earlier, you will also notice that the self-hosting application displays the URL where the runtime-generated Swagger documentation can be viewed. For example:

API documentation is available at https://localhost:8086/api-docs

Navigating to that URL, you should see something like this:

---

Next topic: OData Query Support

---