---
layout: page
title: API documentation
permalink: /reference/api/
menuInclude: yes
menuLink: yes
menuTopTitle: Reference
menuSubTitle: API documentation
menuSubIndex: 2
---

## Introduction

This API documentation, and the associated list of [endpoints](/reference/api/endpoints/), is automatically generated from each repository's
API description files, and specifies how client modules may
access the functionality provided by these modules.
See [further information](#further-information) below.

* view-1: Generated from RAML. Uses pop-up windows for each method and endpoint.
* view-2: Generated from RAML. Plain. Uses one-page view to everything.
* view-3: Uploaded from the module's code build.
* view-4: Generated from OpenAPI OAS.
* [Explain](#explain-views) views.

This list of modules is sorted into functional groups.

{% assign urlAws = "https://s3.amazonaws.com/foliodocs/api" %}
{% assign urlGithub = "https://github.com" %}
{% assign urlSourceXref = "/source-code/map/" %}
{% assign noteRaml = 'This is the shared RAML repository. Each RAML-using module has a certain version of this as a git submodule in their "ramls/raml-util" directory.' %}
{% assign noteSchemaOnly = 'Has only schema and no API descriptions.' %}
{% assign noteReferRamlUtil = 'Refer to the <a href="#raml">raml</a> (raml-util) repository.' %}
{% assign moduleIdEntries = "" | split: ',' %}

{% for group in site.data.apigroup %}
  {% unless group[1].modules %}
    {% continue %}
  {% endunless %}
  {% assign groupId = group[0] %}
  <h2 id="{{ groupId }}"> {{ group[1].title }} </h2>
  <p> {{ group[1].description }} </p>
  {%- for module in group[1].modules -%}
    {%- assign moduleId = module -%}
    {%- assign hasModuleId = moduleIdEntries | where_exp: "item", "item == moduleId" | size %}
    {%- if hasModuleId > 0 -%}
      {%- assign moduleIdNum = hasModuleId | plus: 1 -%}
      {%- assign moduleId = moduleId | append: "-" | append: moduleIdNum  -%}
    {%- endif -%}
    {%- assign moduleIdEntries = moduleIdEntries | push: module -%}
    <h3 id="{{ moduleId }}"> {{ module }} </h3>
    {% assign theRepo = '' %}
    {% for repo in site.data.config-apidocs %}
      {% if repo.name == module %}
        {% assign theRepo = repo %}
        {%- assign repoData = site.data.repos.repos | find: "name", theRepo.name -%}
        {%- assign defaultBranch = repoData.defaultBranch -%}
        {%- capture hasTypeRaml -%}
          {% for apiType in theRepo.metadata.apiTypes %}{% if apiType == "RAML" %}true{% endif %}{% endfor %}
        {%- endcapture -%}
        {%- capture hasTypeOas -%}
          {% for apiType in theRepo.metadata.apiTypes %}{% if apiType == "OAS" %}true{% endif %}{% endfor %}
        {%- endcapture -%}
        {% if theRepo.config.raml.size == 0 and theRepo.config.oas.size == 0 and theRepo.config.upload.size == 0 %}
          {% assign hasApi = false %}
        {% else %}
          {% assign hasApi = true %}
        {% endif %}
        {% if theRepo.name contains 'mod-codex-' %}
          {% assign isRamlUtilOnly = true %}
        {% else %}
          {% assign isRamlUtilOnly = false %}
        {% endif %}
        {%- assign urlSourceXrefLocal = urlSourceXref | append:"#" | append:moduleId -%}
        {%- capture urlConfig %}{{ urlAws }}/{{ theRepo.name }}/config-doc.json{% endcapture -%}
        {% break %}
      {% endif %}
    {% endfor %}
    {% comment %}FIXME: Indenting the <p> caused to display it as preformatted{% endcomment %}
    {% if hasApi == false %}
  <p>{{ noteSchemaOnly }}</p>
  <p> <a href="{{ urlSourceXrefLocal }}">Documentation</a> for {{ moduleId }}. </p>
      {%- continue %}
    {% endif %}
    {% if isRamlUtilOnly %}
  <p>{{ noteReferRamlUtil }}</p>
  <p> <a href="{{ urlSourceXrefLocal }}">Documentation</a> for {{ moduleId }}. </p>
      {%- continue %}
    {% endif %}
    {% if theRepo.name == 'raml' %}
  <p>{{ noteRaml }}</p>
    {% endif %}
    {% unless theRepo.metadata.apiTypes %}
  <p class="attention note-small-2"> Module should now be using "<a href="#explain-api-doc">api-doc</a>" CI facilty. </p>
    {% endunless %}
    {% if theRepo == '' %}
  <p class="attention note-small-2"> No entry for {{ module }} in config-apidocs.json </p>
    {% endif %}
<table class="api">
  <thead>
    <tr>
      <th class="raml" title="APIs and link to source"> Source </th>
      <th class="view" title="View 1: generated by raml2html default"></th>
      <th class="view" title="View 2: generated by raml2html plain"></th>
      <th class="view" title="View 3: uploaded from module's code build"></th>
      <th class="view" title="View 4: generated by redocly"></th>
    </tr>
  </thead>
  <tbody>
    {%- for file in theRepo.config.raml -%}
      {% capture urlSource %}{{ urlGithub }}/{{ theRepo.org }}/{{ theRepo.name }}/blob/{{ defaultBranch }}/{{ file }}{% endcapture %}
      {% capture fileName %}{{ file | split: "/" | last | replace_first: ".raml", "" }}{% endcapture %}
      {% capture rowId %}{{ theRepo.name }}-{{ fileName }}{% endcapture %}
      {% capture subdir %}{% if hasTypeRaml == "true" %}r/{% endif %}{% endcapture %}
      {% capture urlDocR %}{{ urlAws }}/{{ theRepo.name }}/{{ subdir }}{{ fileName }}.html{% endcapture %}
      {% capture urlDocP %}{{ urlAws }}/{{ theRepo.name }}/p/{{ fileName }}.html{% endcapture %}
    <tr id="{{ rowId }}">
      <td> <a href="{{ urlSource }}">{{ file }}</a> </td>
      <td class="view"> <a href="{{ urlDocR }}">view-1</a> </td>
      <td class="view"> <a href="{{ urlDocP }}">view-2</a> </td>
      <td class="view"> </td>
      <td class="view"> </td>
    </tr>
    {%- endfor -%}
    {%- for file in theRepo.config.upload -%}
      {% capture fileName %}{{ file | replace_first: ".html", "" }}{% endcapture %}
      {% capture rowId %}{{ theRepo.name }}-{{ fileName }}{% endcapture %}
      {% capture urlDocU %}{{ urlAws }}/{{ theRepo.name }}/u/{{ file }}{% endcapture %}
    <tr id="{{ rowId }}">
      <td> {{ fileName }} </td>
      <td class="view"> </td>
      <td class="view"> </td>
      <td class="view"> <a href="{{ urlDocU }}">view-3</a> </td>
      <td class="view"> </td>
    </tr>
    {%- endfor -%}
    {%- for file in theRepo.config.oas -%}
      {% capture urlSource %}{{ urlGithub }}/{{ theRepo.org }}/{{ theRepo.name }}/blob/{{ defaultBranch }}/{{ file }}{% endcapture %}
      {% capture fileName %}{{ file | split: "/" | last | replace_first: ".yaml", "" | replace_first: ".yml", "" }}{% endcapture %}
      {% capture rowId %}{{ theRepo.name }}-{{ fileName }}{% endcapture %}
      {% capture urlDocU %}{{ urlAws }}/{{ theRepo.name }}/s/{{ fileName }}.html{% endcapture %}
    <tr id="{{ rowId }}">
      <td> <a href="{{ urlSource }}">{{ file }}</a> </td>
      <td class="view"> </td>
      <td class="view"> </td>
      <td class="view"> </td>
      <td class="view"> <a href="{{ urlDocU }}">view-4</a> </td>
    </tr>
    {%- endfor -%}
  </tbody>
</table>
<p>
<a href="{{ urlSourceXrefLocal }}">Documentation</a> for {{ moduleId }}.
<a href="{{ urlConfig }}">API data</a>.
</p>
  {% endfor %}
{% endfor %}

## Missing API documentation

The following list of modules are missing the configuration for generating their API documentation.

{% for moduleId in site.data.api-missing %}
<h3 id="{{ moduleId }}"> {{ moduleId }} </h3>
<p class="attention note-small-2"> Module should be using "<a href="#explain-api-doc">api-doc</a>" CI facilty. </p>
{% endfor %}

## Further information

### Generated during CI

The API documents are generated by the continuous integration (CI) task "[api-doc](/guides/api-doc)" for each repository during the "merge to main branch" phase or upon module release.
So the documentation does not relate to feature development branches.

### Versioned API Docs

To find documentation for each module release version, amend the URL of each generated document view to add the version number (major.minor).

For example mod-circulation 23.5.\*:
* [https://s3.amazonaws.com/foliodocs/api/mod-circulation/23.5/r/circulation.html](https://s3.amazonaws.com/foliodocs/api/mod-circulation/23.5/r/circulation.html)
* [https://s3.amazonaws.com/foliodocs/api/mod-circulation/23.5/p/circulation.html](https://s3.amazonaws.com/foliodocs/api/mod-circulation/23.5/p/circulation.html)
* List of endpoints: [https://s3.amazonaws.com/foliodocs/api/mod-circulation/23.5/config-doc.json](https://s3.amazonaws.com/foliodocs/api/mod-circulation/23.5/config-doc.json)

For example mod-search 3.2.\*:
* [https://s3.amazonaws.com/foliodocs/api/mod-search/3.2/u/mod-search.html](https://s3.amazonaws.com/foliodocs/api/mod-search/3.2/u/mod-search.html)
* [https://s3.amazonaws.com/foliodocs/api/mod-search/3.2/s/mod-search.html](https://s3.amazonaws.com/foliodocs/api/mod-search/3.2/s/mod-search.html)
* List of endpoints: [https://s3.amazonaws.com/foliodocs/api/mod-search/3.2/config-doc.json](https://s3.amazonaws.com/foliodocs/api/mod-search/3.2/config-doc.json)

### Version numbers

The generated API documentation has a "version number" at the top in brackets. This originates from each module's API description file "version" property.

This property is mostly used inconsistently by module developers.
Instead refer to each module's ModuleDescriptor.

### Explain "views" {#explain-views}

For each module, the "views" of its documentation are generated from the same source API description file, but using different presentation software.
Some modules use RAML (so `view-1` and `view-2`), others use OpenAPI OAS (so `view-4`).

  * `view-1`: Generated from RAML. Uses pop-up windows for each method and endpoint.
    * via [raml2html](https://github.com/raml2html/raml2html) with default theme.
  * `view-2`: Generated from RAML. Plain. Uses one-page view to everything.
    * via [raml2html](https://github.com/raml2html/raml2html) with [plain theme](https://github.com/folio-org/raml2html-plain-theme/tree/folio-589).
  * `view-3`: Uploaded from the module's code build.
    * via CI [doUploadApidocs](/guides/jenkinsfile/#do-upload-apidocs).
  * `view-4`: Generated from OpenAPI OAS.
    * via Redocly [ReDoc](https://github.com/Redocly/redoc).

### Encourage use api-lint {#explain-api-lint}

Modules should now be using the GitHub Workflow "[api-lint](/guides/api-lint/)".

### Encourage use api-doc {#explain-api-doc}

Modules should now be using the GitHub Workflow "[api-doc](/guides/api-doc/)".

### Explain API data

When api-doc generates the API documentation for a module, it also maintains a data file "config-doc.json" which lists the "API data" (description filenames and endpoints) that it discovered about the module. Follow its link.

### Explain gather api-doc config {#explain-gather-config}

For modules that are now using the "api-doc" CI facility, there is an automated daily workflow "[gather-config-apidocs](https://github.com/folio-org/folio-org.github.io/actions/workflows/gather-config-apidocs.yml)" which collects the "API data" configuration changes and issues a pull-request.
Note that the PR must be merged on that day.

So there will be a daily delay for new (or deleted) entries to be listed in their table.
Updates to the actual generated API documents for each module do [happen](#generated-during-ci) automatically, being deployed during their “merge to main branch” phase.

### Linking to API Docs tables {#explain-link-api-docs}

Each section of this page can be directly linked to (e.g. [#mod-circulation](#mod-circulation)).
Similarly each row of a module's documentation table (e.g. [#mod-circulation-change-due-date](#mod-circulation-change-due-date)).

### Which module/interface/endpoint {#module-interface-endpoint}

* See the gathered list of [endpoints](/reference/api/endpoints/).
* See assistance for [How to determine which module handles which interface and endpoint](/faqs/how-to-which-module-which-interface-endpoint/).

### Other notes

* The asterisk `*` denotes that this is a shared set of RAML files.
The generated documents are for this module's current raml-util, but the link to the source RAML file is to the head of the default branch of the shared
"[raml](#raml)" repository.

* A field with property `"folio:isVirtual": "true"` doesn't exist at the API and cannot be searched with that API.  An external tool like `mod-graphql` may merge in that field, see [linked field schema extension](https://github.com/folio-org/mod-graphql/tree/master/src/autogen#option-1-json-schema-extensions).

<div class="folio-spacer-content"></div>