README.md 4.04 KB
Newer Older
Linda Toth's avatar
Linda Toth committed
1
# API Design Guidelines
Linda Toth's avatar
Linda Toth committed
2

3 4
## Introduction
Conexxus and IFSF have worked with retailer and supplier (developer) members to assemble a set of documents to describe how to create an API for consideration as an industry standard.  While there are many languages, formats, and tools available to create APIs, Conexxus and IFSF are focussing on those that are most standardized, and most likely to be useful in a variety of the environments in Convenience Retail computing.  
Linda Toth's avatar
Linda Toth committed
5

David Ezell's avatar
David Ezell committed
6
## Rationale for Selections
7 8 9 10 11 12
Specifically, the participants have singled out the following tools and standards as having the broadest scope:
- Open API Specification 3.0 - formerly "Swagger," this API definition format has become the de facto standard for APIs.
- JSON-Schema 0.7 - as standards organizations, we require a way to define and compose message content.  JSON-Schema is the emerging standard in JSON family of tools, and is compatible with OAS 3.0.
- HTML5 - Capabilities in HTML are ubiquitous, and are included in almost all server and client side development environments.
  
## Documents
David Ezell's avatar
David Ezell committed
13
### [API Design Rules for JSON](https://gitlab.openretailing.org/public-standards/api-design-guidelines/blob/master/Open%20Retailing%20API%20Design%20Rules%20for%20JSON.pdf)
14 15 16

This document describes the Open Retailing (fuel retailing and convenience store) style guidelines for the use of JSON based APIs, including property and object naming conventions. These guidelines are based on best practice gleaned from IFSF, Conexxus, OMG (IXRetail), W3C, Amazon, Open API Standard and other industry bodies.

David Ezell's avatar
David Ezell committed
17
### [API Implementation Guide - Security](https://gitlab.openretailing.org/public-standards/api-design-guidelines/blob/master/Open%20Retailing%20API%20Implementation%20Guide%20-%20Security.pdf) 
18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39

This document describes the Fuel Retailing and Convenience Store API implementation guidelines for security.

### [API Implementation Guide - Transport Alternatives](https://gitlab.openretailing.org/public-standards/api-design-guidelines/blob/master/Open%20Retailing%20API%20Implementation%20Guide%20-%20Transport%20Alternatives.pdf)
This document describes the Fuel Retailing and Convenience Store transport layer alternatives for RESTful web services carrying JSON based APIs, as well as some justification for the selections made.

### [Design Rules for APIs OAS 3.0](https://gitlab.openretailing.org/public-standards/api-design-guidelines/blob/master/Open%20Retailing%20Design%20Rules%20for%20APIs%20OAS3.0.pdf)

This document describes the Open Retailing (fuel retailing and convenience store) style guidelines for the use of RESTful Web Service APIs, specifically the use of the OAS3.0 file format and referencing of relevant JSON Schemas from that file. These guidelines are based on best practice gleaned from OMG (IXRetail), W3C, Amazon, Open API Standard and other industry bodies.
These guidelines are not to be considered a primer for how to create APIs.  There are thousands of documents and blog posts about APIs and best-practices for creating them.  This guide is rather a set of practices to serve as “guardrails” to ensure that Open Retailing APIs have a consistent design

### [Joint API Data Dictionary (proposed)](https://gitlab.openretailing.org/public-proposed-standards/api-data-dictionary)

This is the API Data Dictionary (“Dictionary”), jointly owned by the IFSF (www.ifsf.org) and Conexxus (www.conexxus.org), and shared in order to assist in the use of our international standards.  The Dictionary is open to the public and everybody is allowed to use them. For example, we expect many users will find the Dictionary helpful to understand fuel retailing and to define further innovative and collaborative APIs.

### API Webinars 

Each month Conexxus hosts complimentary public webinars on a variety of topics, including webinars on APIs.  Please visit our Webinar Library to view recordings and upcoming webinars, which can be filtered by topic.

### More information

If you have comments, or would like us to consider changes to any of these items, please either open an issue (in GitLab) or email support@openretailing.org.