Conceptual API Documentation Structure

Owned by Andy Mayer
Last updated: Jan 27, 2020Version comment
3 min read

This Example is generated directly from the Github Markdown Format file: ONAPcommon.md

Use <ctrl><shift>M in Atom to view markdown when editing

Note the MD file embedded inside the swagger needs to replace the newlines with "\n"

To do this in the Atom Editor:

  • open "find / replace", select "Use Regex" shown as ".*"

  • To replace newlines: find: "\r?\n|\r" (without quotes)  AND replace: "\\n" (without quotes)



--------------------------------------------------------------------

About the ONAP Snacking API

The API Description may be multiline, and GitHub Flavored Markdown, GFM syntax, can be used for rich text representation.

API Overview

General Description (short)

What the API does; Purpose of the API; Who should use the API; Why use the API

For Example: This ONAP Style Sample Rest API provides the requestor with access to snack related information from the ONAP Food component and was originally introduced into ONAP in the Frankfurt Release.

Relationship and Dependencies

Requirements and use cases, other Interface Specs, Standards, etc.

For Example: This API is build from related standards, including the PopCorn Forum and SNAK.

API Structure and Approach

Short overview of various API components, e.g. envelope and payload design

Getting Started with the API (Hello World)

How to obtain Credentials and access token; Creating accounts; Making REST API Calls (e.g., sandbox vs live) (where); Very simple Try it for yourself (e.g., CURL / Postman sample)

Basic instructions to users on how to use the API, such as host port, authentication, common error codes, test environment, etc., as well as links to additional resources (such as ONAP Use Cases), plus other details that would help other developers start using the API. might want to provide some basic instructions to users on how to use Swagger UI.

SDK quick intro

Quick description of Swagger environment, tools, etc.

How to start the client side implementation

  • Code generation, patterns etc.

  • Module/Library dependencies

  • Hello word client calls

How to start the server side implementation

  • Code generation, patterns etc.

  • Module/Library dependencies

  • Hello word server responses

API Description

Includes summary of information drawn from API definitions in OpenAPI / Swagger files

Resource Endpoint / Resource Quick Reference

Includes one-line summaries of each endpoint/resource

Data Schema

Main API Entities

Describe the major entities used in the API

Payload data structures

If any, describe the appropriate data structures that are included within payload of the API.

Security on the API

Authentication; Authorization; Credentials/access token; etc.

Response Codes

The meaning of Status Codes & Errors

Rate Limits and Thresholds

Requests per unit time allowed; Pagination

Validation constraints

Describe any behavioral and structural validation constraints

Assumptions

For example, any Pre/Post conditions

API Interactions and Flows

Interaction Examples

Illustrate sequence of client calls to this API, possibly based on Use Cases, presented with diagrams, tables, etc such as: High-level Concepts and inter dependencies API Interaction and Flows using BPMN, UML Sequence diagrams Description of alternative paths in scenario / Error handling scenarios Try it for yourself Sample-Code (CURL or Postman): Simple and Cut and paste ready

Sample CURL Call

curl -X GET \"https://serverRoot:54321/modeling/sampleApi/v1/snacks/314\" -H \"accept: application/json;charset=utf-8\"

Example Response Values

[ { \"id\": 314, \"name\": \"Crunchy Chips\", \"tag\": \"salty\" } ]

Tutorials

Reference any tutorials or use cases. May use links.

API Mapping Details

Includes:

  • Mapping between use cases/requirements and API calls

  • Mapping between IPS/UML model and API data schema (if needed)

Glossary

API Version

The version number has major, minor and revision numbers. E.g. v1.0.0 Only the major version number (without the minor number and revision number) is held in the URL. APIs are described with a major version with “v” following the API Name, e.g.: nbi/api/v4/productOrder. The schema associated with a REST API must have its version number aligned with that of the REST API.

The major version number is incremented for an incompatible change. The minor version number is incremented for a compatible change. For minor modifications of the API, version numbering must not be updated, provided the following backward compatibility rules are respected: New elements in a data type must be optional (minOccurs=0) Changes in the cardinality of an attribute in a data type must be from mandatory to optional or from lower to greater New attributes defined in an element must be optional (absence of use=”required”) If new enumerated values are included, the former ones and its meaning must be kept If new operations are added, the existing operations must be kept New parameters added to existing operations must be optional and existing parameters must be kept

For major modifications of the API, not backward compatible and forcing client implementations to be changed, the major version number must be updated.