FSD SKG-IF API

FSD SKG-IF API is a new public interface (an API) of the Finnish Social Science Data Archive (FSD). This interface follows a shared approach known as the Scientific Knowledge Graph Interoperability Framework (SKG-IF).

The FSD SKG-IF API is FSD's first public OpenAPI for sharing the rich descriptive information (metadata) about the research datasets archived at FSD. OpenAPI is a standard way to clearly document an API so that both people and computer tools can quickly understand what data is available and how to request it, and it is currently the most used standard for sharing information using REST API. REST APIs make systems interoperable, easy to integrate, and scalable because they follow clear, uniform web standards while OpenAPI gives a clear, standardized way to describe your APIs so humans and machines instantly understand how they work. Overall, OpenAPI improves cooperation between organizations because it makes the interface predictable and easier to integrate with other services.

The FSD SKG-IF API is mainly intended for machine-to-machine use (for example, when different services automatically exchange information). However, people can also use it to search and retrieve information from FSD's available endpoints by following the provided instructions.

SKG-IF is a common set of rules that helps different research information systems “speak the same language.” It was first developed by the Research Data Alliance SKG-IF Working Group to make it easier to share and combine research information across organizations and disciplines. Since then, SKG-IF has been updated in OSTrails project so that it can be described using OpenAPI, a widely used way to describe what an API can do and how to use it.

SKG-IF is being taken into use by several research infrastructures in different fields (e.g. ESFR and CLARIN) and many EOSC projects such as GraspOS, SciLake, and FAIRCORE4EOSC. OpenAIRE has also been an early adopter. FSD's work on implementing the SKG-IF API is funded by the Research Council of Finland through the project FSD AIMS 2030.

SKG-IF provides a structured way to describe information with the data model and an OpenAPI specification which is a practical way to share information between the systems. With SKG-IF, systems can exchange data about six main building blocks called core entities and how they relate to each other:

• Research Product – the main entity which may be literature, research data, software, or other
• Agent – may represent a Person, an Organization, or a generic Agent linked to other entities e.g. a contributor of the research product
• Grant – describes the funding of a project related to research product
• Venue – models a publishing gateway of a research product
• Topic – defines terms that can be used to describe a research product
• Data Source – represents the storage location of a research product

The central entity is the research product. In the underlying data model, each of these entities are separate, and they are connected by references (links) to one another.

SKG-IF is designed to work across disciplines, so that research information from different fields can be compared and combined more easily. It enhances interoperability between different scientific disciplines. The API specification is a practical adaptation of the data model. Instead of only pointing to other entities via links, the API often includes some key details directly inside the main entity, research product record. For example, in the model, a “contribution” might only link to an agent (a person/organization) and their affiliation. In the API, the contributor details can be included directly in the contribution section, so users and systems can see important information right away. The same approach is used for topics, where a research product can include topic information directly, with labels in different languages grouped under the same vocabulary term using external controlled vocabulary services.

For more details, visit: https://skg-if.github.io/interoperability-framework/.

Documentation

FSD SKG-IF API is documented using the standard OpenAPI / Swagger UI format as described earlier. To ensure interoperability with other implementations of the SKG-IF, the documentation is based on the original SKG-IF OpenAPI specification. There are only minor modifications to reflect the FSD’s current implementation. Endpoints (specific web addresses returning data when requested) that are not available yet are labeled “Not yet implemented”, and filters (options added to request narrowing the result) that do not apply in this version of the API are shown with a strikethrough. At present, the API exposes only a subset of FSD's full metadata of the research data (such as title, abstract, authors, topics from CESSDA Topic Classification and The field of study classification by the Finnish Ministry of Education and Culture, publication date, and access rights). In other words, you can use this service to find and identify datasets using key descriptive information and use some filters to narrow down the search result. Nevertheless, it does not include all available metadata or possible features of the SKG-IF API.

OpenAPI Documentation

Multilingual topic mapping using external vocabulary APIs

Topic information exposed by the FSD SKG-IF API is based on established controlled vocabularies. During the transformation of FSD metadata into the SKG-IF format, external vocabulary APIs are used to resolve topic identities so that labels in different languages (for example “Yhteiskuntatieteet” and “Social sciences”) are linked to the same vocabulary concept and exposed as language-specific labels of a single term.

The following controlled vocabularies and services are used for topic identity resolution and label mapping:

• CESSDA Topic Classification, accessed via the CESSDA Vocabulary Service API
  
• The Field of Study Classification by the Finnish Ministry of Education and Culture, accessed via the Finto API

Endpoints

Currently only research product endpoint representing research data is available. In the near future, also publications (research literature) related to research data will be implemented in this research product endpoint. There are also plans to add more endpoints e.g. Organization and Person later.

All endpoints support pagination. Default: 10 items per page, sorted by FSD ID descending. Use ?page=N and ?page_size=M to modify navigation.

Products endpoint

/skg-if/products?page=2&page_size=20

Filters

The API supports two types of filters: attribute filters and convenience filters.

Attribute filters match fields directly from the underlying SKG-IF entity such as product and use exact matching (for example identifiers, identifier schemes, contributor names, or funding information).

Convenience filters provide shortcuts for common discovery use cases such as text search (title or abstract), ORCID-based matching, or affiliation matching using ROR identifiers.

Any number of filters can be combined using the filter= parameter.

?filter=field:value,otherfield:othervalue

?filter=cf.search.title_abstract:health,contributions.by.name:statistics%20finland

?filter=contributions.by.name:tuominen%2C visa

Below are examples of commonly used filters. The complete set of supported filters is defined in the OpenAPI specification.

Search metadata in the response

The API includes metadata describing pagination and result sets:

{
  "meta": {
    "local_identifier": "...?page=2&page_size=20",
    "entity_type": "search_result_page",
    "previous_page": {
      "local_identifier": "...?page=1&page_size=20",
      "entity_type": "search_result_page"
    },
    "next_page": {
      "local_identifier": "...?page=3&page_size=20",
      "entity_type": "search_result_page"
    },
    "part_of": {
      "local_identifier": "...",
      "entity_type": "search_result",
      "total_items": 2165,
      "first_page": {
        "local_identifier": "...?page=1&page_size=20",
        "entity_type": "search_result_page"
      },
      "last_page": {
        "local_identifier": "...?page=109&page_size=20",
        "entity_type": "search_result_page"
      }
    }
  }
}

The meta section describes where the current page fits within the overall result set. It provides direct links to the previous and next pages (when available), as well as links to the first and last pages of the full search result. The total number of results is found from part_of.total_items which in the example has value 2165. This makes it easy to browse paginated responses manually and helps clients understand total item counts and navigation options.