Systems and APIs

UiB apidoc collects documentation and structured information about systems and the programming interfaces (APIs) they use and provide.

A system in this context is a set of related programs that implement some service. Some systems provide services for other systems to consume. We call such services for APIs. In the context of apidoc API means any interface provided by one system meant to be consumed by programs in other systems. APIs can be exposed via HTTP, LDAP and other network protocols, libraries for specific programming languages, command line scripts, views or stored procedures in a relational database and even shared files.

Systems are given short symbolic names. These names can be nested to form hierachies of related systems. APIs are given short symbolic names in the namespace of the system they are associated with.

Systems can be assigned to classes for further categorization where needed.

Apidoc Files

The systems and their APIs are described by apidoc files; either written in XML or a markdown based format. The schema document describes the full details of the XML format. The tutorial document provide further examples.

This is an example of an XML apidoc file:

<apidoc>
  <system refname="foo">
    <abstract>nothing says foo like we do</abstract>
    <description>
      to foo or not to foo that's a question
      yadayada,...
    </description>
  </system>
</apidoc>

This simply describes that there exists a system called foo and then provide the short and long descriptions of what the purpose of this system is.

The markdown version of the same information is:

# foo -- nothing says foo like we do

to foo or not to foo that's a question
yadayada,...

In general the markdown syntax is much easier to use if you maintain these files by hand; while the XML format might be more appropriate for automatically generated apidoc files. Internally the markdown files are converted to the XML format before they are processed further. The apidoc.md document described the details of the markdown format.

The Apidoc Documentation Set

The set of systems that apidoc knows about are those described by the apidoc files in the apidoc folder. Any valid file dropped in this folder will be automatically incorporated into the set and presented on the apidoc website.

Files with .xml extension are assumed be XML files with a single <apidoc> root element conforming to the apidoc schema.
Files with .md extension are converted to XML using the apidoc md2xml filter and should be in the apidoc.md format.
Any other files are simply ignored.

These are the options for populating the apidoc folder:

commit XML or markdown files directly to the apidoc git repo. This requires that you have access to git and know how to edit text files directly.
maintain the apidoc file describing a system among the sources of the system itself and have somebody with git access register the file in the external.yml file.
create some system that extracts api information directly for the sources and provide a webservice to generate the apidoc file. Have somebody with git access register an entry for this source in the external.yml file.

Entries in the external.yml file are downloaded periodically and any updates to them are automatically commited to the apidoc folder.