Tutorial 02 06 API Documentation
The Microsoft library that we use to implement API versioning also has the ability to automatically produce Swagger API documentation for the web service, and this behavior is now enabled by default in all Harmony Core services.
You will notice that each time you start the self-hosting application, it displays the URL where the runtime-generated API documentation can be viewed. If you are working in a standard Harmony Core environment, this URL will be:
- In Visual Studio, press F5 (start debugging) to start the self-hosting application.
You should see the console window appear, with the messages confirming that your service is running.
- Open a web browser and navigate to the API documentation URL:
You should see the API documentation home page, which at this point in the tutorial should look something like this:
As you can see there are section headings for each of the main entity types, and below those headings are colored lines that represent the various endpoints that are available for that entity type.
Currently, you only see one operation for each entity, which is a GET operation to retrieve the entire collection of entities.
- Click the blue
GETbutton below theCustomers
You should see the operation expand and information about the input parameters and response types for the operation is displayed. The parameter information looks like this:
This operation does not actually support any input parameters, but if it did there would be fields for you to enter sample data to be sent to the service, and while there are fields to allow you to enter various OData query options, those fields are currently disabled, because those capabilities have not yet been enabled in your Harmony Core service.
The response information tells you what HTTP return codes could be generated by the endpoint, as well as the format of any data returned (JSON in this case) and also provides an example of what the return data will look like. In this case, the endpoint returns an array of objects, each of which has various properties (customerNumber, name, street, etc.)
Notice also a Try it Out button near the top-right of the parameter information. This button puts the page into a mode where you can actually interact with the running web service.
- Click the
Try it Outbutton, then scroll down and click theExecutebutton.
This causes the API documentation web app to actually issue an HTTP GET request to the endpoint that you are looking at, and display the response from the endpoint right in the documentation page, like this:
First, you can see an example of t CURL command that you could use to make the same request from the command line, then a confirmation of the URL of the endpoint being accessed. Following that, you will see the actual response from the web service endpoint, an HTTP 200 (OK) in this case, along with the data that was returned. And notice that at the lower right corner of the data window is a download button that lets you download the raw data in a JSON file.
Below the data, you can also see all of the HTTP response headers that were returned along with the data.
This is all very useful information for a programmer who intends to write code to interact with the web service. If the programmer understands the HTTP protocol then this documentation presents them with everything they need to know to access your service.
- When you are finished, stop the service by terminating the self-hosting program.
Next topic: Single Entity Endpoints