Welcome
This is the introduction page for all things IFSF API related. It’s a good place to start if you are unfamiliar with the new technology, jargon and tools associated with APIs, and you want a quick summary of what is available.
If you are familiar with APIs, Git Repositories, JSON and OAS 3.0 then you can jump straight to the Shared Git Repository here.
Background
IFSF have been writing design rules, Implementation guides, an API Data Dictionary and developing collections of APIs since 2015. Everything has been upgraded to current (Early 2020) best practise, to a git repository and are shared with Conexxus.
Previous versions are stored in the IFSF Standards archive under Part 4-01. These must no longer be used. The current recommended versions are stored in open retailing git repositories, shared with Conexxus. The design guides and dictionary are public. The APIs and tools (such as forecourt device simulator) are for members access only.
Process and “How to” Guide
IFSF and Conexxus have developed short YouTube videos to introduce member and guests to the new technology and the way IFSF and Conexxus want to see it implemented. These are available on www.openretailing.org. A list of Frequently Asked Questions is also available. These FAQs include links to videos.
The main development platform is a Git Repository called GitLab. Git Lab documentation is excellent and comprehensive (although full of new jargon) and can be viewed here.
IFSF and Conexxus have adopted the standard Gitlab workflow; which is described here.
Gitlab workflow is very flexible and certain parts have bee specified in more detail – for example to enable our tools to work effectively.
These are described in the Open Retailing GitLab Development Process document, available here and on GitLab.
API video guides can be viewed here.
This document requires supporting documents to be produced and the templates for these can be found here . Specifically the templates include
API Resource Identification Template and an example
Joint Conexxus-IFSF Threat Model Template – Designers
Joint Conexxus-IFSF Threat Model Template – Implementor
The process for approving an API – whether it initiated as a donated API or from a Joint (IFSF and Conexxus) Working Group is described in documents.
These documents can be found in the project Gitlab openretailing repository project folder called Work in Progress/process-procedures.
As well as containing MS-Word versions of the design rules and Implementation guides (described below) it also contains:
Joint IP Submission Form
Open Retailing GitLab Development Process
Process for Donated APIs
Published API Collections
The following API Collections are in the openRetailing Git repository. You need to be a member of IFSF to access these. Contact support@openretailing.org and request access to all folders. For members who don’t want to view raw YAML source code project files the fuel retailing related API Collections can be viewed at docs.openretailing.org. However you will need a GitLab User name and password.
Forecourt API Collection: This covers all the Use Cases that are defined in Part 3-27 between a POS and FDC for fuel. That is everything except car wash and EPS. Specifically Dispensers, Price Poles, Prices and Tank Gauges are included.
Closed Loop Payment API: Version 1.0 of this API covers Issuer initiated payments for closed loop payment instruments such as fuel cards. The next release will be extended to cover Merchant initiated payments.
WSM: This covers the five fundamental wet stock management use cases; i.e. Tank Stock, Movements, Turnover (from Dispenser meters), Sales (as registered at POS) and Fuel Reconciliation (identifies discrepancies).
REMC (Remote Equipment Monitoring and Control): This covers the maintenance management Use Cases for Asset Identification (equipment, devices and applications), Events (Error, Warning and Information) and Points (Reading values). The scope of REMC has been broadened to include all types of assets, not just equipment. The collection of APIs is called Site Asset Data Collection.
Remote Fueling Point Approval: This covers the most common above site authorisation Use Case for “mobile payment”. The single use case implemented is pre-auth (usually outdoor) for fuel only. Post-Pay, shop goods and services (e.g. car wash) are not included. No PCI relevant data is required (i.e. on site authorisation is not included). IFSF and Conexxus have extended the scope of RFPA to include more mobile payment related Use Case. RFPA has therefore been merged into a more generic mobile payment API collection. This is Work in Progress and can be found here https://gitlab.openretailing.org/work-in-progress/mobile-api-collections/.
Prices: This is a subset within the Forecourt-API-Collection. This covers the use cases for fuel and car wash (programme and options) pricing. Both setting and reporting prices between a client and server.
Simulators and Test Tools
IFSF and Conexxus have developed a Forecourt Device Controller Simulator to confirm that the Design Rules and Implementation Guides and the resulting Forecourt-API-Collection really work.
Forecourt Device Controller Simulator: The simulator is a simple prototype developed using eight of the Forecourt-API-Collection APIs. The simulator is running permanently on a cloud server. The source code for the Forecourt Device Controller Simulator can be viewed here.
API Specification Validator: IFSF and Conexxus have developed a tool (actually a simple npm project) that consumes a .yaml API Definition File(s) and compares them with the Open Retailing Design Rules. The Forecourt-API-Collection was validated using this tool. The source code and how to run the tool can be found here.