## The content (content being images, text or any other medium contained within this document which is eligible of copyright protection) are jointly copyrighted by Conexxus and IFSF. All rights are expressly reserved.
## IF YOU ACQUIRE THIS DOCUMENT FROM IFSF. THE FOLLOWING STATEMENT ON THE USE OF COPYRIGHTED MATERIAL APPLIES:
You may print or download to a local hard disk extracts for your own business use. Any other redistribution or reproduction of part or all of the contents in any form is prohibited.
You may not, except with our express written permission, distribute to any third party. Where permission to distribute is granted by IFSF, the material must be acknowledged as IFSF copyright and the document title specified. Where third party material has been identified, permission from the respective copyright holder must be sought.
You agree to abide by all copyright notices and restrictions attached to the content and not to remove or alter any such notice or restriction.
Subject to the following paragraph, you may design, develop and offer for sale products which embody the functionality described in this document.
No part of the content of this document may be claimed as the Intellectual property of any organisation other than IFSF Ltd, and you specifically agree not to claim patent rights or other IPR protection that relates to:
the content of this document; or
any design or part thereof that embodies the content of this document whether in whole or part.
For further copies and amendments to this document please contact: IFSF Technical Services via the IFSF Web Site (www.ifsf.org).
## IF YOU ACQUIRE THIS DOCUMENT FROM CONEXXUS, THE FOLLOWING STATEMENT ON THE USE OF COPYRIGHTED MATERIAL APPLIES:
Conexxus members may use this document for purposes consistent with the adoption of the Conexxus Standard (and/or the related documentation); however, Conexxus must pre-approve any inconsistent uses in writing.
Conexxus recognizes that a Member may wish to create a derivative work that comments on, or otherwise explains or assists in implementation, including citing or referring to the standard, specification, protocol, schema, or guideline, in whole or in part. The Member may do so, but may share such derivative work ONLY with another Conexxus Member who possesses appropriate document rights (i.e., Gold or Silver Members) or with a direct contractor who is responsible for implementing the standard for the Member. In so doing, a Conexxus Member should require its development partners to download Conexxus documents and schemas directly from the Conexxus website. A Conexxus Member may not furnish this document in any form, along with any derivative works, to non-members of Conexxus or to Conexxus Members who do not possess document rights (i.e., Bronze Members) or who are not direct contractors of the Member. A Member may demonstrate its Conexxus membership at a level that includes document rights by presenting an unexpired digitally signed Conexxus membership certificate.
This document may not be modified in any way, including removal of the copyright notice or references to Conexxus. However, a Member has the right to make draft changes to schema for trial use before submission to Conexxus for consideration to be included in the existing standard. Translations of this document into languages other than English shall continue to reflect the Conexxus copyright notice.
The limited permissions granted above are perpetual and will not be revoked by Conexxus, Inc. or its successors or assigns, except in the circumstance where an entity, who is no longer a member in good standing but who rightfully obtained Conexxus Standards as a former member, is acquired by a non-member entity. In such circumstances, Conexxus may revoke the grant of limited permissions or require the acquiring entity to establish rightful access to Conexxus Standards through membership.
This project contains documents that define the Conexxus/IFSF API Design Guidelines.
## 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.
* If the project is within the *Work in Progress* group, it contains Microsoft word documents, and the changes for any given development branch will be presented in "track changes" mode.
* If the project is within the *Public Standards* group. it contains the pdf versions of the documents.
## Rationale for Selections
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
### [API Design Rules for JSON](https://gitlab.openretailing.org/public-standards/api-design-guidelines/blob/master/Open%20Retailing%20API%20Design%20Rules%20for%20JSON.pdf)
## Guides in this Project
The guides fall into the following categories:
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.
### Design Rules
1.**[Open Retailing API Design Rules for JSON](Open%20Retailing%20API%20Design%20Rules%20for%20JSON.docx)**
This guide covers naming of properties, use of booleans, and other basic design topics.
2.**[Open Retailing Design Rules for APIs OAS3.0](Open%20Retailing%20Design%20Rules%20for%20APIs%20OAS3.0.docx)**
Topics in this guide describe how to define an API (using the API Definition File (ADF), written in YAML), expected directory layouts, and other important topics.
This document describes the Fuel Retailing and Convenience Store API implementation guidelines for security.
This guide breaks out security considerations into a separate document. Since ideas about security tend to change relatively rapidly, having this guide in a separate document makes the rest of the documents more stable.
### [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.
4.**[Open Retailing Implementation Guide - Transport Alternatives](Open%20Retailing%20API%20Implementation%20Guide%20-%20Transport%20Alternatives.docx)**
Transport alternatives include web sockets, native (TCP/IP) sockets, MQTT, AMQP, etc. This document explains the current design choices for the API work and how that might change in the future, depending on changes to the cloud coding conventional wisdom.
### [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.
