---
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 software version, amend the URL of each generated document view to add the version number (major.minor).\
For example [mod-circulation](#mod-circulation), do `mod-circulation/23.1/...`

### 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.
So there will be a 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>