Technical description of the service in the API Catalogue
Each service should have a general description as well as a technical description which is automatically harvested to the API CatalogueOpens in a new window. from the Data Exchange Layer. These technical descriptions should be either:
- WSDL descriptions in case of SOAP services or
- OpenAPI 3 descriptions in case of REST services
You have to add the description for your service in the Security Server WebUI and then it will be shown automatically in the API Catalogue.
Document your REST architecture services in accordance with the OpenAPI specification. The API Catalogue displays a preview of your OpenAPI descriptions so that a person scrolling through the API Catalogue can focus on the most important details about your service. If you include links in your descriptions, make sure that they work and are not e.g. internal links. For more information about OpenAPI, see:
Please note, that the description has to be in accordance with the OpenAPI 3.0 version so that the automatic preview is available in the API catalogue. If you use OpenAPI 2.0 version for example, you will have to add the description manually to the API catalogue.
Services that are missing the technical description (either WSDL or OpenAPI 3) are shown as unknown services in the API Catalogue.
Why is my service shown as unknown in the API Catalogue?
Services are shown as unknown in the API Catalogue if they are missing technical service descriptions from the Security Server WebUI. Without a service description, API Catalogue cannot recognise whether the service is a REST or SOAP service.
Usually, an unknown service is a REST service that has been added to the Data Exchange Layer using the REST API Base Path. API Catalogue cannot recognise these types of services as REST services. The technical description for a REST service has to be in OpenAPI 3 format for it to show automatically in the API Catalogue.
We recommend adding REST services to the Data Exchange Layer by using OpenAPI 3 Description path in the Security Server WebUI. This way the API Catalogue can recognise the service and show the technical interface description automatically. Even if you cannot add the technical description in OpenAPI 3 format, we still recommend adding a description, for example as an attachment.
Sometimes, SOAP service’s WSDL-description can disappear. In this case, the service also shows as unknown in the API Catalogue.
Adding a description for an unknown service
Adding a description depends on whether the service is a REST or SOAP service.
1. For a REST service that has been added using REST API Base Path
If you cannot add a service description in an OpenAPI 3 format, add the service description as an attachment for a subsystem in the API Catalogue. The technical description can be, for example, an OpenAPI 2 JSON file. See for example the service description attachment in Forest Centre’s subsystem.
- Add an attachment from the subsystem’s page by selecting Manage > Attachments > Add new attachment.
- Fill in the fields. Give the attachment a descriptive name so that service consumers know to which service the technical description belongs to.
- Lastly, select Add.
In addition, add a short, understandable description of the service and mention that the technical description in added as an attachment. Add a description from the service’s page by selecting Manage. Your service will still show as an unknown service, but the users who want to implement your service will understand its operation better with the help of the technical description.
You can change the services that have been added using REST API Base Path into OpenAPI 3 Description services. To do this, add the service first by using OpenAPI 3 Description path and test that it works correctly and then you can remove the original REST API Base Path service.
2. For a SOAP service
SOAP service needs to have a WSDL description added to the Security Server WebUI so that the API Catalogue can show the service description automatically.
In case your SOAP service shows as unknown service in the API Catalogue, check from the Security Server WebUI if the WSDL description has disappeared. If the description has disappeared, add the WSDL description again. It will be added automatically also to the API Catalogue. Read more about how to add a WSDL description on a Security Server. See also how the WSDL description should be. Your service should show normally in the API Catalogue the next day.
If you did not find an answer to your problem from these instructions, please contact our customer support at palveluvayla@palveluvayla.fiOpens in a new window.