-
Notifications
You must be signed in to change notification settings - Fork 51
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
6dba831
commit b0adfe8
Showing
2 changed files
with
111 additions
and
58 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
|
|
||
| # Build ONE Record API ontology documentation | ||
|
|
||
| **(1) Install pyLODE with pip** | ||
| ```bash | ||
| $ pip install pylode | ||
| ``` | ||
|
|
||
| **(2) Generate HTML document from TTL file** | ||
| ```bash | ||
| $ python -m pylode ONE-Record-API-Ontology.ttl -o minimal.html | ||
| ``` | ||
|
|
||
| **(3) Open Documentation** | ||
| ```bash | ||
| $ open minimal.html | ||
| ``` | ||
|
|
||
| # Build ONE Record API specification documentation | ||
|
|
||
| **(1) Install MkDocs and Material for MkDocs** | ||
| ```bash | ||
| $ pip install mkdocs mkdocs-material | ||
| ``` | ||
|
|
||
| **(2) Start built-in development server to preview documentation** | ||
| ```bash | ||
| $ mkdocs serve | ||
| INFO - Building documentation... | ||
| INFO - Cleaning site directory | ||
| INFO - Documentation built in 0.58 seconds | ||
| INFO - [09:59:34] Watching paths for changes: 'docs', 'mkdocs.yml' | ||
| INFO - [09:59:34] Serving on http://127.0.0.1:8000/ | ||
| ``` | ||
|
|
||
|
|
||
| **(3) Resolve symlinks, and publish documentation to GitHub Pages** | ||
| ```bash | ||
| $ rm -rf docs/changelog.md; cp CHANGELOG.md docs/changelog.md | ||
| $ rm -rf docs/license.md; cp ../../LICENSE docs/license.md | ||
| $ rm -rf docs/assets/ONE-Record-API-Ontology.ttl; cp ONE-Record-API-Ontology.ttl docs/assets/ONE-Record-API-Ontology.ttl | ||
| $ rm -rf docs/assets/ONE-Record-API-Class-Diagram.md; cp ONE-Record-API-Class-Diagram.md docs/assets/ONE-Record-API-Class-Diagram.md | ||
| $ rm -rf docs/assets/ONE-Record-API-OpenAPI.yaml; cp ONE-Record-API-OpenAPI.yaml docs/assets/ONE-Record-API-OpenAPI.yaml | ||
| $ rm -rf docs/assets/ONE-Record-API-OpenAPI.recommended.yaml; cp ONE-Record-API-OpenAPI.recommended.yaml docs/assets/ONE-Record-API-OpenAPI.recommended.yaml | ||
| $ rm -rf docs/assets/ONE-Record-API-Ontology.csv; cp ONE-Record-API-Ontology.csv docs/assets/ONE-Record-API-Ontology.csv | ||
| $ mkdocs gh-deploy --ignore-version | ||
| $ ln -fs ../CHANGELOG.md docs/changelog.md | ||
| $ ln -fs ../../../LICENSE docs/license.md | ||
| $ mkdir -p docs/assets | ||
| $ ln -fs ../../ONE-Record-API-Ontology.ttl docs/assets/ONE-Record-API-Ontology.ttl | ||
| $ ln -fs ../../ONE-Record-API-Class-Diagram.md docs/assets/ONE-Record-API-Class-Diagram.md | ||
| $ ln -fs ../../ONE-Record-API-OpenAPI.yaml docs/assets/ONE-Record-API-OpenAPI.yaml | ||
| $ ln -fs ../../ONE-Record-API-OpenAPI.recommended.yaml docs/assets/ONE-Record-API-OpenAPI.recommended.yaml | ||
| $ ln -fs ../../ONE-Record-API-Ontology.csv docs/assets/ONE-Record-API-Ontology.csv | ||
| ``` | ||
| *This creates / uses the branch gh-pages to deploy the documentation and make it available as GitHub page* | ||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,60 +1,55 @@ | ||
| # Full API documentation | ||
| [Link to API documentation](https://iata-cargo.github.io/ONE-Record/) | ||
|
|
||
| # Build ONE Record API ontology documentation | ||
|
|
||
| **(1) Install pyLODE with pip** | ||
| ```bash | ||
| $ pip install pylode | ||
| ``` | ||
|
|
||
| **(2) Generate HTML document from TTL file** | ||
| ```bash | ||
| $ python -m pylode ONE-Record-API-Ontology.ttl -o minimal.html | ||
| ``` | ||
|
|
||
| **(3) Open Documentation** | ||
| ```bash | ||
| $ open minimal.html | ||
| ``` | ||
|
|
||
| # Build ONE Record API specification documentation | ||
|
|
||
| **(1) Install MkDocs and Material for MkDocs** | ||
| ```bash | ||
| $ pip install mkdocs mkdocs-material | ||
| ``` | ||
|
|
||
| **(2) Start built-in development server to preview documentation** | ||
| ```bash | ||
| $ mkdocs serve | ||
| INFO - Building documentation... | ||
| INFO - Cleaning site directory | ||
| INFO - Documentation built in 0.58 seconds | ||
| INFO - [09:59:34] Watching paths for changes: 'docs', 'mkdocs.yml' | ||
| INFO - [09:59:34] Serving on http://127.0.0.1:8000/ | ||
| ``` | ||
|
|
||
|
|
||
| **(3) Resolve symlinks, and publish documentation to GitHub Pages** | ||
| ```bash | ||
| $ rm -rf docs/changelog.md; cp CHANGELOG.md docs/changelog.md | ||
| $ rm -rf docs/license.md; cp ../../LICENSE docs/license.md | ||
| $ rm -rf docs/assets/ONE-Record-API-Ontology.ttl; cp ONE-Record-API-Ontology.ttl docs/assets/ONE-Record-API-Ontology.ttl | ||
| $ rm -rf docs/assets/ONE-Record-API-Class-Diagram.md; cp ONE-Record-API-Class-Diagram.md docs/assets/ONE-Record-API-Class-Diagram.md | ||
| $ rm -rf docs/assets/ONE-Record-API-OpenAPI.yaml; cp ONE-Record-API-OpenAPI.yaml docs/assets/ONE-Record-API-OpenAPI.yaml | ||
| $ rm -rf docs/assets/ONE-Record-API-OpenAPI.recommended.yaml; cp ONE-Record-API-OpenAPI.recommended.yaml docs/assets/ONE-Record-API-OpenAPI.recommended.yaml | ||
| $ rm -rf docs/assets/ONE-Record-API-Ontology.csv; cp ONE-Record-API-Ontology.csv docs/assets/ONE-Record-API-Ontology.csv | ||
| $ mkdocs gh-deploy --ignore-version | ||
| $ ln -fs ../CHANGELOG.md docs/changelog.md | ||
| $ ln -fs ../../../LICENSE docs/license.md | ||
| $ mkdir -p docs/assets | ||
| $ ln -fs ../../ONE-Record-API-Ontology.ttl docs/assets/ONE-Record-API-Ontology.ttl | ||
| $ ln -fs ../../ONE-Record-API-Class-Diagram.md docs/assets/ONE-Record-API-Class-Diagram.md | ||
| $ ln -fs ../../ONE-Record-API-OpenAPI.yaml docs/assets/ONE-Record-API-OpenAPI.yaml | ||
| $ ln -fs ../../ONE-Record-API-OpenAPI.recommended.yaml docs/assets/ONE-Record-API-OpenAPI.recommended.yaml | ||
| $ ln -fs ../../ONE-Record-API-Ontology.csv docs/assets/ONE-Record-API-Ontology.csv | ||
| ``` | ||
| *This creates / uses the branch gh-pages to deploy the documentation and make it available as GitHub page* | ||
| # Welcome to ONE Record API Standard Specifications! | ||
|
|
||
| This repository contains the specifications and ontology of ONE Record API Standard. | ||
|
|
||
| # Purpose | ||
|
|
||
| This ONE Record API specification is part of the ONE Record standard. | ||
| It defines a standard, programming language-agnostic interface for the interaction with the ONE Record Web API. | ||
| This ONE Record API specification supports the effective implementation of ONE Record compliant APIs. | ||
| It aims to provide detailed realistic use cases and examples for the various API features while maintaining the necessary technical depth for implementers. | ||
|
|
||
| # Prerequisites | ||
|
|
||
| It is assumed that the reader is familiar with the ONE Record data model, REST APIs (also known as RESTful APIs), and JSON-LD. | ||
|
|
||
| # API documentation | ||
|
|
||
| Use the following link to reach the API documentation website: [Link to API documentation](https://iata-cargo.github.io/ONE-Record/) | ||
|
|
||
| # Supporting Documents | ||
|
|
||
| - [Changelog](changelog.md) contains a list of all notable changes for each version of the ONE Record API specification. | ||
| - [ONE Record API ontology](assets/ONE-Record-API-Ontology.ttl) provides the vocabulary and data classes for the data model used in the ONE Record API. | ||
| - [Tabular overview of ONE Record API ontology](assets/ONE-Record-API-Ontology.csv) is a tabular representation of the ONE Record API ontology and describes the ONE Record API data classes, their properties as attributes, descriptions and valid values. | ||
| - [ONE Record API class diagram](assets/ONE-Record-API-Class-Diagram.md) is a visual representation of the ONE Record API ontology and describes the ONE Record API data classes, their properties as attributes, and the relationship that can exist between the classes. | ||
| - [OpenAPI specification (minimum)](assets/ONE-Record-API-OpenAPI.yaml) describes the prescribed API endpoint structure of a ONE Record server implementation | ||
| - [OpenAPI specification (recommended)](assets/ONE-Record-API-OpenAPI.recommended.yaml) describes the recommended API endpoint structure of a ONE Record server implementation | ||
| - [Postman collection](assets/ONE-Record-API-Collections.postman_collection) contains demo HTTP requests that demonstrate how to interact with the various ONE Record API endpoints and can be used to playback the examples provided in this document. | ||
|
|
||
|
|
||
| # Document Version | ||
|
|
||
| **Version:** 2.0.0-dev | ||
|
|
||
| **Status:** Draft; not yet approved by the COTB / CSC | ||
|
|
||
| !!! note | ||
| This document is a draft and is subject to edits. | ||
| Discussion on this specification is highly encouraged and please contact [[email protected]](mailto:[email protected]) with any comments or suggested improvements.<br/> | ||
| The version of the ONE Record API specification is incremented when the API specifications are endorsed by the IATA Cargo Operations Technology Board (COTB). The first version (v1.0) of the API specification was released in Aug 2020 (endorsed in Mar 2020). | ||
|
|
||
| ## Dependencies | ||
|
|
||
| The ontology of the ONE Record API uses data classes defined in the ONE Record cargo ontology. | ||
| Therefore, this ONE Record API version 2.0.0-dev requires the ONE Record cargo ontology 3.0.0 or later. | ||
|
|
||
| # Conventions | ||
|
|
||
| The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). | ||
|
|
||
| # License | ||
|
|
||
| This document is licensed under MIT license (see [License](license.md) for details). | ||
|
|
||
|
|