Skip to content

Tutorial 02 06 API Documentation

Jump to bottom
mattl91 edited this page Mar 2, 2023 · 10 revisions

Harmony Core Logo

API Documentation

The Microsoft library that we use to implement API versioning can also automatically produce Swagger API documentation for the web service, and this behavior is now enabled by default in all Harmony Core services.

VIDEO: Creating a Basic Solution

If you are working in a standard Harmony Core environment, the runtime-generated API documentation can be viewed here:

Viewing API Documentation

  1. 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.

  1. 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:

API Documentation

If you scroll down this page, you'll see there are section headings for each of the main entity types. And below those headings are colored blocks that represent the endpoints that are available for the entity types.

Currently, you'll see only two operations for each entity. One is a GET operation (e.g., /Items) to retrieve the entire collection of entities. The other is a GET operation for $count, which is not operational (because we haven't set the Enable collection count endpoints option in the Harmony Core CLI tool).

  1. Click the blue GET button immediately below Customers.

You should see the operation expand, and information about response types for the operation should be displayed (you may need to scroll down to this this):

API Documentation Responses

The response information tells you which HTTP return codes could be generated by the endpoint, as well as the format of any data returned (JSON in this case). It 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.

  1. Click Try it Out, and then scroll down and click the Execute button.

This causes the API documentation web app to issue an HTTP GET request to the endpoint and then display the response from the endpoint right in the documentation page, like this:

API Documentation Response

Under the Curl label, you'll see the curl command you could use to make the same request from the command line. This is followed by the URL of the endpoint being accessed. And under that, you will see the actual response from the web service endpoint—HTTP 200 (OK) in this case—along with the data that was returned. Notice that at the lower right corner of the data window is a download button that enables you to download the raw data in a JSON file.

Below the data, you can also see the HTTP response headers that were returned 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, this documentation presents everything the programmer needs to know to access your service.

Stop the Service

  1. When you are finished, stop the service by terminating the self-hosting program.

Next topic: Single Entity Endpoints

Clone this wiki locally