Guide for administrator
Entering information into the API Catalogue
1 The API descriptions of the API Catalogue are important in terms of the usability of the Data Exchange Layer
API descriptions are essential for the usability of the API Catalogue and the entire Data Exchange Layer as they tell the person browsing the Catalogue what kind of APIs are available through the Data Exchange Layer. In this guide, you will be informed how to descripe APIs.
The information describing the APIs (so-called metadata) mustbe updated by the organisations themselves in the user interface of the API Catalogue.The general descriptions of APIs and the main user’s contact details are examples of such metadata.
The details of the API’s interfaces, such as the name and the interface descriptions, are automatically updated to the API Catalogue from the Data Exchange Layer.
How do you edit the information on the organisation in the API Catalogue?
To amend the information on your organisation, go to the information on your organisation in the API Catalogue and click the Manage button. You must be logged in the API Catalogue and have the rights to edit the information on your organisation in the Catalogue.
The API Catalogue main user in your organisation will give you the rights to edit the data. If your organisation does not have a person with rights to edit the information on your organisation, request the rights and access codes from API Catalogue maintenance: firstname.lastname@example.org.
What should be said in the description of the organisation?
Provide general information about your organisation briefly in the description of the organisation: what organisation is it and what does it do? You can also mention in a few sentences what kind of APIs and what data your organisation offers through the Data Exchange Layer. You can provide a link to the organisation’s website in the description.
For example, the description of the Digital and Population Data Services Agency provides the organisation’s basic details. It also includes links to the dvv.fi website.
The organisation should have its logo/image in the API Catalogue. You can upload the logo of your organisation from your workstation by clicking the blue Upload button.
The Digital and Population Data Services Agency will add the first user. After that, the organisation can manage the users and their rights itself and invite new users. If necessary, request the main user’s user IDs from API Catalogue maintenance: email@example.com.
The API Catalogue has different user roles with different rights:
- Admin: View APIs, Adding an API, Editing an API, Removing an API, Managing the organisation’s members
- Editor: View APIs, Adding an API, Editing an API
- Member: View APIs.
User id, password, status and role are the mandatory user data. A description and a name can also be given to the user, but it is voluntary information.
How do you edit the API information?
To amend the information on your API, go to the information on the API in the API Catalogue and click the Manage button. You must be logged in the API Catalogue and have the rights to edit the information on your organisation in the Catalogue.
The main user in your organisation will give you the rights to edit the information. If your organisation does not have a person with rights to edit the information on your organisation, request the rights and access codes from API Catalogue maintenance: firstname.lastname@example.org.
Please note that you cannot edit the API title in the API Catalogue as the title is automatically retrieved from the Data Exchange Layer.
What should be said in the API description?
The API description is a service promise marketing the interfaces and content information of the API. You should therefore not use language that is too technical when writing the description. Aim for general expressions. Write a compact description but remember to mention all essential information. For example, see the Digital and Population Data Services Agency’s description of the VTJ interface service (in Finnish).
Explain the following in the description:
- What data can be accessed through the API
Explain how other organisations can benefit from the API. This way other organisations get a general idea of the API and can judge whether their organisation should commission the API.
- What kind of restrictions concern the use of the API
Explain what kind of restrictions concern the use of the API. For example, specify who can start to use the API. Also mention any other possible restrictions that may be related, for example, to the times of API use, data access authorisation practices, possible fees and the publicity of the content information.
- How the API is commissioned
Provide instructions on how other organisations must proceed if they would like to find more information about the API or would like to commission it. Describe the commissioning process briefly at a general level and tell where more information is available. The contact details of the API main user are entered in a specific field but if there are several contact details, you can also enter them in the description field.
Also pay attention to the following when drawing up the API description:
- Use formatting
Using different formats makes the text easier to understand. You should divide the description text with the help of subtitles (for example, into the three sections presented above: What / On what conditions / How). You can also use bold text to highlight the most important parts of the description.
Note! Formatting elements can be added to the text by using Markdown markup language. You will see the formatting options by clicking the You can use Markdown formatting elements here section below the description field. Titles can be formatted by adding # in front of the title. For example, you can write in the description field: ”# Criteria for data access ”, which will give you the subtitle you can see in the example on the right. More information on Markdown markup language is available on Markdown Guide website.
- Add a description in Finnish, Swedish and English
The language versions of the description are added to their dedicated fields (below the field for the description in Finnish) and they are visible if the API Catalogue is used in a different language. Remember to also update the language versions when you update the description.
Provide the API with tags that describe the data offered by the API or are essentially related to it. For example, the tags that have been provided for the VTJ interface API are “Population Information System”, “personal identity code”, “personal data”, etc.
In addition to the name and the text fields, the search in the API Catalogue focuses on the tags. An API with good tags is therefore easier to find in the Catalogue When you add tags to the API, you should think about what search words you would use yourself to find the interface service in question.
Period of validity
Under Valid since, you will provide the date from which the API will be in use.
If the API is valid until further notice, you do not need to provide any information in the Valid until section.
However, if the date when the API will be amended or removed from the Data Exchange Layer is known, you should provide it under Valid until.
Environment refers to the different environments of the Data Exchange Layer. It could therefore be used to separate the APIs of the test and production environments. The test environment is, however, currently not used so you do not need to enter any information in the section concerned.
You can publish the API in the API Catalogue of the data Exchange Layer for everyone browsing the Catalogue to see if you change its status to Public. If the status is Private, only the organisation managing the API can see the API in the API Catalogue.
For example, you can use the Private status if the API descriptions have not been completed yet and you therefore do not want to display the API publicly in the Catalogue.
If other organisations can use the API, always select yes.
API contact details
Provide the API main user’s contact details so that organisations interested in the API can request more information about it.
If possible, provide the organisation’s sector-specific email address, not a personal address. This way, enquiries concerning the API will always processed regardless of absences of individual members of personnel.
4 Attachment files (Data and Resources) provide instructions for the commisioning and use of and individual interface
The API’s resources page or pages consist of the API abstract and an automatically created preview of the content of the actual API file. In addition, it is possible to also enter other data into the attachment files, such as a description of the attachment file. Create a resources page separately for each interface. The VTJ interface API is an example of an API with several attachment files.
The description of the API attachment file should be a technical instruction for the commissioning and use of an individual interface. In the description, describe how the interface in question can be commissioned and what should be taken into account when using it,
The following data can be provided for the attachment file:
- Description FI, SV, EN
- Type FI, SV, EN
- Possible charge Yes/No/See description
- File format
- Valid since
- Valid until
- API data FI, SV, EN
- Availability FI, SV, EN
- Service Level Agreement FI, SV, EN
- Average response time
- Service status FI, SV, EN
The API Catalogue compiles in one place the APIs offered through the Suomi.fi Data Exchange Layer, in other words the interface services and the parties maintaining them. The API Catalogue enables organisations planning to commission the interface services of the Data Exchange Layer to see what APIs and data are available in the Data Exchange Layer. The API described in the Catalogue can be implemented by agreeing on it with the maintainer of the API.
The API Catalogue always contains up-to-date information on the organisations that have connected to the Suomi.fi Data Exchange Layer and their APIs. The most recent information on the APIs is harvested into the API Catalogue every night. The central server of the Suomi.fi Data Exchange Layer harvests the data from the customer-specific API servers.
In addition to the data harvested automatically from the Data Exchange Layer, organisations themselves provide in the Catalogue interface such information (metadata) describing the APIs that is related to the organisation, users, the API and the attachment files.
- Organisation in an organisation using the Data Exchange Layer.
- User is a member of a user organisation or, for example, a technical operator that may act on behalf of the user organisation.
- API: An interface service to which one or more interfaces can connect.
Example: In the VTJ API (in Finnish), the basic details of the API have been described on one page. In addition to this, a list of resources of which at least one is a WSDL file that is automatically harvested from the central servers of the Data Exchange Layer is provided.
- Interface: Connects to only one service and always contains one technical description, which is displayed visually in the API Catalogue (for example, a WSDL or XML description).
Example: Several interfaces connect to the VTJ API, some of which are instructive such as sample messages. For example, see the VTJ API interface ”Henkilön tunnuskysely (in Finnish)”.
- Attachment file: An API always has at least one attachment file, a WSDL description that can be harvested. In addition to this mandatory one, there may also be other attachment files, for example, instructions or examples of query and response messages.