COMMUNICATIONS SPECIFICATIONS OVER REST

Document name .....COMMUNICATIONS SPECIFICATIONS OVER REST

Last saved date ............................................12/13/2016 10:37:00 AM
Revision number.................................................................. DRAFT 1.1
Part Number ........................................................................... Part II.3
 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 2 of 34

(This page is intentionally blank)

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 3 of 34

1 COPYRIGHT AND INTELLECTUAL PROPERTY RIGHTS STATEMENT

The content (content being images, text or any other medium contained within this document which is
eligible of copyright protection) is Copyright © IFSF Ltd 2011. All rights expressly reserved.

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.

USE OF COPYRIGHT MATERIAL

Subject to the following paragraph, you may design, develop and offer for sale products that 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.

This document was written by the IFSF – Device Integration Working Group. The latest revision of this
document can be downloaded from the Internet
Address: www.ifsf.org

Any queries regarding this document should be addressed to: [email protected]

2 DOCUMENT REVISION SHEET

Version Release Date Details Author

1.00 1 Initial draft John Carrier (IFSF Project Manager) /
Gonzalo Gomez (OrionTech) / Axel
Mammes (OrionTech)

1.1 Updated template Gonzalo Fernandez Gomez

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 4 of 34

3 DOCUMENT CONTENTS
1 COPYRIGHT AND INTELLECTUAL PROPERTY RIGHTS STATEMENT ..................................................... 3
2 DOCUMENT REVISION SHEET ........................................................................................................... 3
3 DOCUMENT CONTENTS .................................................................................................................... 4
4 REFERENCES ..................................................................................................................................... 5
5 GLOSSARY ......................................................................................................................................... 6
6 INTRODUCTION ................................................................................................................................ 8
6.1 BACKGROUND ............................................................................................................................. 8
6.2 WHAT IS REST? .......................................................................................................................... 8
6.3 ADVANTAGES AND DISADVANTAGES ................................................................................................ 9
7 IFSF RESTFUL REFERENCE ARCHITECTURE ........................................................................................ 9
7.1 CONTEXT DIAGRAM ...................................................................................................................... 9
7.2 COMPONENTS ........................................................................................................................... 10
7.3 SCOPE OF APPLICABILITY .............................................................................................................. 10
7.4 CRITERIA FOR IFSF RESTFUL API.................................................................................................. 11
7.5 SAFETY AND IDEMPOTENCE.......................................................................................................... 12
7.6 HTTP VERBS............................................................................................................................. 12
7.7 URL FORMAT, NAMING CONVENTION AND VERSIONS ...................................................................... 13
7.8 EXPOSING SEVERAL API VERSIONS ................................................................................................. 13
7.9 HTTP HEADERS ......................................................................................................................... 14
7.10 HTTP STATUS CODES ................................................................................................................. 14
7.11 ERROR HANDLING ...................................................................................................................... 14
7.11.1 Success .............................................................................................................................. 14
7.11.2 Functional errors ............................................................................................................... 15
7.11.3 Technical errors ................................................................................................................. 16
7.11.4 Detailed information about errors ..................................................................................... 16
7.12 CONTENT-TYPE .......................................................................................................................... 17
7.13 DATA ENCODING ....................................................................................................................... 17
7.14 CACHING .................................................................................................................................. 17
8 NETWORK AND NETWORK SECURITY .............................................................................................. 18
8.1 PROXIES ................................................................................................................................... 18
8.2 FIREWALL ................................................................................................................................. 18
8.3 TRANSPORT-LAYER SECURITY ........................................................................................................ 18
8.3.1 Certificate Management ....................................................................................................... 19
9 APPLICATION AUTHENTICATION AND AUTHORIZATION ................................................................. 21
9.1 DECOUPLING AUTHENTICATION AND AUTHORIZATION FROM APIS ..................................................... 21
9.2 USING NO AUTHENTICATION ........................................................................................................ 22
9.3 USING USER AND PASSWORD TO AUTHENTICATE USERS ................................................................... 22
9.4 USING API KEYS TO AUTHENTICATE ACCESS ................................................................................... 23
9.5 USING OAUTH2.0 TO AUTHENTICATE API KEYS ............................................................................... 25
9.5.1 Encoding consumer key and secret........................................................................................ 25
9.5.2 Obtain a bearer token ........................................................................................................... 26
9.5.3 Authenticate API requests with a bearer token ..................................................................... 27

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 5 of 34

10 USE-CASES ............................................................................................................................. 27
10.1 ACCESSING A RESOURCE .............................................................................................................. 27
10.2 QUERIES AND FILTER................................................................................................................... 28
10.2.1 Get a resource since the unique identifier ......................................................................... 28
10.2.2 Get a resource since a unique field, different to the unique identifier ............................... 28
10.2.3 Get a resource (or a set of resources) using a combination of fields ................................. 29
10.3 SORTING RESULTS ...................................................................................................................... 30
10.3.1 Client side .......................................................................................................................... 30
10.3.2 Server side ......................................................................................................................... 30
10.4 BULK OPERATIONS...................................................................................................................... 30
10.5 PAGING THE RESULTS .................................................................................................................. 31
10.6 ASYNCHRONOUS CALLS ............................................................................................................... 33
11 REST BACKWARDS COMPATIBILITY ........................................................................................ 34

4 References
[1] IFSF STANDARD FORECOURT PROTOCOL PART II – COMMUNICATION SPECIFICATION
[2] IFSF STANDARD FORECOURT PROTOCOL PART III.I – DISPENSER APPLICATION
[3] Microsoft Developer Network (MSDN) Helps
[4] The Internet Engineering Task Force (IETF®)
[5] Guidelines for Implementation of REST - National Security Agency (NSA)
[6]
[7] HTTP Digest AKAv2 RFC 4169: https://www.ietf.org/rfc/rfc4169.txt
[8] Baseline Requirements Certificate Policy for the Issuance and Management of Publicly-
Trusted Certificates
https://cabforum.org/wp-content/uploads/Baseline_Requirements_V1_3_1.pdf

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 6 of 34

5 Glossary
Internet The name given to the interconnection of many isolated networks into a virtual
single network.

Port A logical address of a service/protocol that is available on a particular computer.

Service A process that accepts connections from other processes, typically called client
processes, either on the same computer or a remote computer.

Socket An access mechanism or descriptor that provides an endpoint for communication.

Socket The combination of the IP address, protocol (TCP or UDP) and port number on a
Address computer that defines the complete and unique address of a socket on a computer

IFSF heartbeat The UDP port to be used by all IFSF compliant devices having been assigned by the
port Internet Assigned Numbers Authority (IANA) as '3486'.

API Application Programming Interface. An API is a set of routines, protocols, and tools
for building software applications

BOS Back Office Server

CD (IFSF) Controller Device

CHP Central Host Platform (the host component of the web services solution)

EB Engineering Bulletin

FP (IFSF) Fuelling Point (in customer terminology the common name is “pump number”)

IFSF International Forecourt Standards Forum

JSON JavaScript Object Notation; is an open standard format that uses human-readable
text
to transmit data objects consisting of attribute-value pairs

REST REpresentational State Transfer) is an architectural style, and an approach to

communications that is often used in the development of Web Services.

TIP IFSF Technical Interested Party

URI Universal Resource Identifier. In computing, a URI is a string of characters used to

identify a name of a resource

URL Universal Resource Locator. The most common form of URI is the uniform resource
locator (URL), frequently referred to informally as a web address.

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 7 of 34

XML Extensible Markup Language is a markup language that defines a set of rules for
encoding documents in a format which is both human-readable and machine-
readable

Protected An access-restricted resource which can be obtained using an OAuth-authenticated

resource request

Resource A server capable of accepting and responding to protected resource requests.

server

Client An application obtaining authorization and making protected resource requests.

Resource An entity capable of granting access to a protected resource.

owner

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 8 of 34

6 Introduction
This document describes the transport of IFSF application messages using HTTP RESTful services. IFSF
message details are described in each corresponding application specification. For the user to quickly
identify REST implementations from current specifications, all REST documents will be identified within
Part 4.

Representational State Transfer (REST) is a software architecture style for building scalable web
services. REST gives a coordinated set of constraints to the design of components in a distributed
hypermedia system that can lead to a higher performing and more maintainable architecture.

RESTful systems typically, but not always, communicate over the Hypertext Transfer Protocol with the
same HTTP verbs (GET, POST, PUT, DELETE, etc.) which web browsers use to retrieve web pages and to
send data to remote servers.

6.1 Background

Representational State Transfer (better known as REST) is a programming philosophy that was
introduced by Roy T. Fielding in his doctoral dissertation at the University of California, Irvine, in 2000.
Since then it has been gaining popularity and is being used in many different areas. Perhaps the best
description of REST is from Roy Fielding himself:

“Representation State Transfer is intended to evoke an image of how a well-designed Web

application behaves: a network of web pages (a virtual state-machine), where the user progresses
through an application by selecting links (state transitions), resulting in the next page (representing
the next state of the application) being transferred to the user and rendered for their use.”

6.2 What is REST?

Representational State Transfer (REST) is an architectural principle rather than a standard or a protocol.
The basic tenets of REST are: simplify your operations, name every resource using nouns, and utilize
the HTTP commands GET, PUT, POST, and DELETE according to how their use is outlined in the original
HTTP RFC (RFC 26163). REST is stateless, does not specify the implementation details, and the
interconnection of resources is done via URIs. REST can also utilize the HTTP HEAD command primarily
for checking the existence of a resource or obtaining its metadata.

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 9 of 34

6.3 Advantages and Disadvantages

Some of the advantages of using REST include:

• Every resource and interconnection of resources is uniquely identified and addressable with a
URI [consistency advantage]
• Only four HTTP commands are used (HTTP GET, PUT, POST, DELETE) [standards compliance
advantage]
• Data is not passed, but rather a link to the data (as well as metadata about the referenced data)
is sent, which minimizes the load on the network and allows the data repository to enforce and
maintain access control [capacity/efficiency advantage]
• Can be implemented quickly [time to market advantage]
• Short learning curve to implement; already understood as it is the way the World Wide Web
works now [time to market advantage]
• Intermediaries (e.g. proxy servers, firewalls) can be inserted between clients and resources
[capacity advantage]
• Statelessness simplifies implementation – no need to synchronize state [time to market
advantage]
• Facilitates integration (mashups) of RESTful services [time to market advantage]
• Can utilize the client to do more work (the client being an untapped resource)

Some of the disadvantages of REST include:

• Servers and clients implementing/using REST are vulnerable to the same threats as any
HTTP/Web application
• If the HTTP commands are used improperly or the problem is not well broken out into a RESTful
implementation, things can quickly resort to the use of Remote Procedure Call (RPC) methods
and thus have a nonRESTful solution
• REST servers are designed for scalability and will quickly disconnect idle clients. Long running
requests must be handled via callbacks or job queues.
• Porting the IFSF Unsolicited Messages mechanism to REST is not trivial. The client must have a
reachable HTTP(S) server and a subscription mechanism is necessary.

7 IFSF Restful reference architecture

7.1 Context diagram

IFSF REST Services exposes CHP services to the Site systems (and vice versa). Site systems must send
the following requests in order to exchange information with a central host platform.

1. POST IFSF Site Data (e.g. Tank stock data, Tank sales data, Tank deliveries data, sales
transaction)
2. GET IFSF Site Data (e.g. Fuel Name, Fuel Price)
3. PUT IFSF Site Data (e.g. overwrite the current tank status (e.g. high water alarm, out of stock))
4. DELETE IFSF Site Data (e.g. remove equipment record from site as no longer present)

The REST services exposed are shown in the diagrams below. The first Figure are those exposed by the
Central Host Platform and the second are those exposed by the Site System.

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 10 of 34

7.2 Components

As seen previously, the components are mainly two:

• The Site System, which manage the information and functionality associated with a site.
• The Central Host Platform, a real time platform and can be a technical integration layer that
sits between the site systems and an Oil company’s (or third party managed service provider’s)
various central, cloud based, and third party application solutions.

7.3 Scope of applicability

From an equipment scope perspective, this specification applies to all the components of a IFSF
systems, and the interrelation between several system of a IFSF ecosystem. From a communications

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 11 of 34

perspective, this specification covers communications between site systems and Central Host
Processors (CHPs), and between CHP applications.

Although not covered in this specification, future releases of this document might cover
communications within site systems. To cover intra site systems communications, additional features
such a discovery services will need to be included in this specification.

This document covers Machine-to-Machine (M2M) integration scenario. Human to Machine

communications scenarios are out of scope of this specification.

7.4 Criteria for IFSF RESTful API

In order to design the IFSF REST-ful API, the following principles are applied:
• Short (as possible). This makes them easy to write down, spell, or remember.
• Hackable ‘up the tree’. The consumer should be able to remove the leaf path and get an
expected page back. e.g. http://mycentralremc.com/sites/12345 you could remove the 12345
site ID identifier and expect to get back all the site list.
• Meaningful. Describes the resource. I should have a hint at the type of resource I am looking at
(a blog post, or a conversation). Ideally I would have a clue about the actual content of the URI
(e.g. a uri like uri-design-essay)
• Predictable. Human-guessable. If your URLs are meaningful, they may also be predictable. If
your users understand them and can predict what a URL for a given resource is then may be
able to go ‘straight there’ without having to find a hyperlink on a page. If your URIs are
predictable, then your developers will argue less over what should be used for new resource
types.
• Readable.
• Nouns, not verbs. A resource is a noun, modified using the HTTP verbs
• Query args (everything after the ?) are used on querying/searching resources (exclusively).
They contain data that affects the query.
• Consistent. If you use extensions, do not use .html in one location and .htm in another.
Consistent patterns make URIs more predictable.
• Stateless.
• Return a representation (e.g. XML or JSON) based on the request headers. For the scope of IFSF
REST implementation, only JSON representations will be supported.
• Tied to a resource. Permanent. The URI will continue to work while the resource exists, and
despite the resource potentially changing over time.
• Report canonical URIs. If you have two different URIs for the same resource, ensure you put
the canonical URL in the response.
• Follows the digging-deeper-path-and-backspace convention. URI path can be used like a
backspace.
• Uses name1=value1;name2=value2 (aka matrix parameters) when filtering collections of
resources.
• Use a plural path for collections. e.g. /sites.
• Put individual resources under the plural collection path. e.g. /sites/123456. Although some
may disagree and argue it be something like /123456, the individual resource fits nicely under
the collection. It also allows to ‘hack the url’ up a level and remove the siteID part and be left
on the /sites page listing all (or some) of the sites.
• The definitions of the URIs will follow the IETF RFC 3986 (https://www.ietf.org/rfc/rfc3986.txt)
that define an URI as a hierarchical form.

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 12 of 34

7.5 Safety and Idempotence

A few key concepts to understand before implementing HTTP methods include the concepts of safety
and idempotence.

A safe method is one that is not expected to cause side effects. An example of a side effect would be a
user conducting a search and altering the data by the mere fact that they conducted a search (e.g. if a
user searches on “blue car” the data does not increment the number of blue cars or update the user’s
data to indicate his favourite colour is blue). The search should have no ‘effect’ on the underlying data.
Side effects are still possible, but they are not done at the request of the client and they should not
cause harm. A method that follows these guidelines is considered ‘safe.’

Idempotence is a more complex concept. An operation on a resource is idempotent if making one

request is the same as making a series of identical requests. The second and subsequent requests leave
the resource state in exactly the same state as the first request did. GET, PUT, DELETE and HEAD are
methods that are naturally idempotent (e.g. when you delete a file, if you delete it again it is still
deleted).

The importance of safety and idempotence is that it allows users to use HTTP and know that their
actions will not change the underlying resource. Of course, this is dependent on uniform usage of the
four HTTP verbs. REST relies heavily on this uniform usage so that there are no unintended
consequences or unexpected actions. Without a uniform interface, each resource would require a
custom interface that understands how that resource expects to send and receive information. This
would undermine one of the main goals of REST – simplicity and ease of use.

The key point to remember is that in order to ensure that an operation / implementation is RESTful,
these methods must be used as they were defined in RFC 2616, the HTTP 1.1 specification. If
implementations abuse these methods, they not only depart from RESTful behaviour, but also
jeopardize the application’s ability to interoperate with other RESTful capabilities.

7.6 HTTP Verbs

HTTP defines many verbs, applicable in the Internet world. REST API is a subset of the internet world,
so it not apply all the HTTP verbs, but just four as a minimum, 5 as a maximum.
The next table summarises the IFSF APIs accepted verbs. This point is strict and the use of others verbs
will not be allowed.

Verb Safe / Usage

Idempotent
The HEAD command is used to retrieve the same headers as that of a GET
response but without any body in the response. The method returns the
HEAD S/I
same response as the GET function except that the server returns an
empty body.
Returns the representation of a resource. Note we are saying
representation instead of resource. This is because a REST API works with
GET S/I
a representation of a resource (in XML or json, e.g), but not work directly
with a resource (which exists in the real world). GET should never cause
This document is Intellectual property of IFSF
 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 13 of 34

any side effects due to its use, in other words it should be used in a safe
and idempotent manner.
Creates the representation of a new resource into a collection. A
POST -/- collection is a set of resource representations. The representation of the
new object is transferred using the body of the HTTP request,
Updates a representation of an existing resource. The body of the request
represent the new state of the representation of a given resource. PUT
PUT -/I
should only be used to create new resources only when clients can decide
URIs of resources (otherwise use POST).
Deletes a given resource instance. The representations of the resource
DELETE -/I will be no longer available after the execution of a DELETE operation.
Responses to the DELETE method are not cacheable.

7.7 URL Format, Naming Convention and Versions

A URL (Uniform Resource Locator) is the way you may identify a resource in a network. In the case of
the IFSF API’s, the URL will identify a resource provided by a computer system, which will be consumed
by other computer systems. In the context of this document, the RESTful approach defines an API as a
bundle of resources well defined, and uniquely identified. Some examples of resources could be
Country, User or Dispenser.

A URL has three main components:

• the mechanism used to access the resource
• the server where the resource is located
• the specific name of the resource

The following is the proposed API URL format:

http[s]://{hostName}[:{port}]/{APIName}/v{APIVersionNumber}[[/[resource]][?{parameters}]

{hostName} is the host name or IP address of the RESTful web server

{port} is the listening port (default 80 for http or 443 for https)
{APIName} is the application name, such as
ifsf-fdc, for forecourt device controller
ifsf-wsm, for wet stock management server
ifsf-eps, for electronic payment server
ifsf-pp, for price pole server
ifsf-cw, for car wash server
ifsf-tlg, for tank level gauge server
ifsf-remc, for remote equipment monitoring
{APIVersionNumber} consists of major[.minor] where:
major corresponds to the major version number
minor corresponds to the optional minor version number in two digits
{resource} object or collection of objects that are consumed
{parameters} is parameter[&parameters]
{parameter} is parameterName[=Value] where parameterName cannot be a verb.

7.8 Exposing several API versions

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 14 of 34

In order to support several client releases consuming different API versions, a server can expose
multiple versions of the same API.

For example,
http://api.ifsf.org/ifsf-fdc/v2/sites
http://api.ifsf.org/ifsf-fdc/v2.01/sites

7.9 HTTP Headers

The IFSF will use only the standard HTTP headers for its API, and only the following Headers:
● Accept, to negotiate the representations of a resource, and the version of the referenced
resource.
● Accept-language: to negotiate the language of the representation of a resource (for
internationalization). If this header is not specified, the application will respond in its default
implementation language.
● Authorization: to manage the authentication and authorization of a user and application to a
given resource.
● Accept-encoding: Used to compress server response.
● Cache-Control: Used to direct proxy servers not to cache responses
● Content-type: to inform the representation of a query or a response.

7.10 HTTP Status Codes

As said previously, RESTful APIs works over HTTP, and an important part of HTTP are the status codes,
which represent the status (success or failure) of the request and interchange of information between
the parties.

Applied to IFSF, will be used the status codes according http://www.iana.org/assignments/http-status-

codes/http-status-codes.xhtml, summarized below:

1xx: Information at transport level.

2xx: Success. The request was accepted and processed successfully
3xx: Redirection, indicate the consumer must perform some actions to execute the request.
4xx: Consumer mistake / failure. The request was not be accepted by the server and will not
be processed.
5xx: Server failure. The request could not be processed at the time of the request. The
consumer should retry later.

The following section summarises the HTTP status codes used by IFSF APIs:

7.11 Error handling

There will be three types of situations when a client performs a request to a server that will be managed
in different ways

7.11.1 Success

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 15 of 34

These codes will be used when a request is executed successfully:

HTTP Code Situation When it will be used

200 Ok Successful
A resource has been created successfully, in response to a
201 Created POST or PUT command. The body should contains the
representation of the resource
The request has been accepted and will be processed
202 Accepted
asynchronously. The body is intentionally empty.
Used as a response to GET command, when the resource
204 No content exists, but without representation. e.g. when a query does
not retrieve any value.
The server successfully processed the request, but is not
205 Reset Content returning any content. Unlike a 204 response, this response
requires that the requester reset the document view.
The server is delivering only part of the resource (byte
serving) due to a range header sent by the client. The range
Partial Content
206 header is used by HTTP clients to enable resuming of
(RFC 7233)
interrupted downloads, or split a download into multiple
simultaneous streams.

7.11.2 Functional errors

This type are related with errors or mistakes not produced by the server itself, and not related with
technical issues, but related to functional validations or client request mistakes.
In case of errors, the following status code will be returned:

HTTP Code Situation When it will be used

The request is not valid and will not be processed. The
400 Bad request
consumer should change the data and retry.
The user or application credentials are incorrect or not
401 Unauthorized
presented.
The consumer don’t have permission to access the
403 Forbidden
resource.
404 Not found The URI asks for a resource that doesn’t exists.
The HTTP method is not allowed. For example, when some
application want to execute a TRACE or CONNECT verb.
Method not
405 Another situation is given when the user are not allowed to
allowed
perform some action with a resource representation (e.g. a
consumer want to delete a tank, but it’s not allowed)
Indicates that the resource at this end point is no longer
410 Gone
available. Useful as a blanket response for old API versions
Unsupported
415 The media type could not be processed, because it’s invalid.
media type
Unprocessable The media type and representation are valid, but with
422
entity semantic mistakes.
Too many Associated with SLA. When a server receives too many
429
requests request in a short period of time.

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 16 of 34

Business rule
490 Reserved for business validations.
conflict

7.11.3 Technical errors

Technical errors are situations non-handled or unexpected in the server side. The code used to inform
this situation are the following:

HTTP Code Situation When it will be used

Internal server
500 Internal error in the server side.
error
The server either does not recognize the request method,
501 Not implemented or it lacks the ability to fulfil the request. Usually this implies
future availability (e.g., a new feature of a web-service API).
The proxy or gateway receive a wrong answer from the
502 Bad gateway
server.
Service The server could not process the request at the moment,
503
unavailable due to an internal failure or a maintenance.

7.11.4 Detailed information about errors

The functional or technical errors described previously, will have a detailed description, defined as a
JSON object as a response, with the following structure:
• Error code: a unique identifier of the error. Each IFSF application communication standard must
define its error code catalog.
• Reference ID: Optional server side error identifier. Client must support receiving the value.
• User message: A message for end-user usage.
• Technical message: A message for technical usage, with more information.
• Stack Trace: Optional stack trace information for debugging purposes.
• Error code links: a link point to more information about the error (optional).

See below an example of a correct JSON error response:

{
“errorCode”: 146,
“referenceId”: 4584050844,
“userMessage”: “Error saving your data!!!”,
“technicalMessage”: “Error saving into Tank, duplicated ID”,
“stackTrace”:”java.lang.NullPointerException
pump.presentation.controllers.UnixServerJobController.handleRequest(UnixServerJ
obController.java:66)
org.springframework.web.servlet.mvc.SimpleControllerHandlerAdapter.handle(Sim
pleControllerHandlerAdapter.java:48)
javax.servlet.http.HttpServlet.service(HttpServlet.java:803)
org.springframework.web.filter.CharacterEncodingFilter.doFilterInternal(Character
EncodingFilter.java:96)

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 17 of 34

org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilte
r.java:76)”,
“errorCodeLink”: ”http://developers.ifsf.com/errors/146”
}

7.12 Content-type

The IFSF API use the Media Type standard to define the types of representations of a resource, and the
HTTP headers Accept and Content-type to communicate the types of representation between parties.
The IFSF API accepts application/json only, but it would be possible to extend it in the future to other
media types such as application/xml.

For example, to get the list of tanks in a site (e.g. with 12345 as identifier) in JSON, a user must use the
following command:

Request:
GET http://api.ifsf.org/ifsf-remc/v1/sites/8652345
Accept: application/json

Response:
HTTP 200 OK
Content-type: application/json
{
"Site": {
"id": "8652345",
"name": "Wimbledon",
"type": "COCO",
"address": "7 Privet Drive Wimbledon",
"country": "UK",
}
}

7.13 Data Encoding

The IFSF API use compression to reduce the bandwidth requirements of the communication. Both
parties must support gzip encoding. The development parties can add other encoding schemes, but
every API must support at least gzip.

For example, the following request requires compression of the results in gzip format:

Request:
GET http://api.ifsf.org/ifsf-remc/v1/sites/8652345
Accept-Encoding: gzip

7.14 Caching
This document is Intellectual property of IFSF
 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 18 of 34

The IFSF API must ensure that information is not cached in intermediate servers and that the client will
always receive the current response from the server.

The clients must include the following header:

Request:
GET http://api.ifsf.org/ifsf-remc/v1/sites/8652345
Cache-Control: no-cache

8 Network and Network Security

IFSF restful implementation can be achieved by connecting devices over local networks, WAN and
Internet. Adequate security considerations should be taken while implementing IFSF through Internet.

As with any networking environment, security measures should be implemented in line with the results
of risk assessment for a given installation. Details are dependent on the network installation and hence
our outside the scope of this document. However, the following items should be considered.

IFSF is not responsible for auditing security during the certification process. It is up to the
implementation team to make sure that security is consistent with standards at the time of
implementation and are properly kept up to date during the product life cycle.

8.1 Proxies

A proxy server is a server that sits between a client and server. A proxy is mostly transparent to end-
users, so you think you are sending HTTP request messages directly to a server, but the messages are
actually going to a proxy.

• Proxies can perform a wide range of one or more services. The following paragraphs highlight
a few of the popular services.
• Load balancing proxies can take a message and forward it to one of several web servers on a
round-robin basis, or by knowing which server is currently processing the fewest number of
requests.
• SSL acceleration proxies can encrypt and decrypt HTTP messages, taking the encryption load
off a web server.
• Proxies can provide an additional layer of security by filtering out potentially dangerous HTTP
messages. Specifically, messages that look like they might be trying to find a cross-site scripting
(XSS) vulnerability or launch a SQL injection attack.
• Caching proxies will store copies of frequently access resources and responding to messages
requesting those resources directly.

8.2 Firewall

Firewall implementation is beyond the scope of this document.

8.3 Transport-layer security

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 19 of 34

TLS must be supported by all parties, although it can be disabled during implementation. Whenever TLS
is active, the following rules must be observed:

TLS version: servers and clients MUST support TLS 1.2. SSL 2.0, SSL 3.0, TLS 1.0 and TLS 1.1 are
forbidden. TLS 1.3 is currently in draft, so it is not considered.

Key exchange: servers and clients MUST support DHE-RSA (forward secrecy), which is part of both TLS
1.2 and TLS 1.3 draft.

Block Ciphers: servers and clients MUST support AES-256 CBC. DES, 3DES, AES-128 and AES192 are
forbidden.

Data integrity: servers and clients MUST support HMAC-SHA256/384. HMAC-MD5 and HMAC-SHA1 are
forbidden.

Vendors are allowed to support other TLS/key exchange/cipher and MAC algorithms.

Certificates signed using MD5 or SHA1 must be not be trusted. All vendors MUST support certificates
signed using SHA2. Self-signed certificates are allowed.

Vendors MUST provide mechanisms for authorized users and technicians to disable security algorithms
in order to keep up with security industry recommendations. As reference for vulnerability publications,
please refer to:

NIST: National vulnerability database (https://nvd.nist.gov/).

Mitre: Common Vulnerabilities and Exposures (https://cve.mitre.org/)

8.3.1 Certificate Management

Each equipment should provide a documented means of loading certificates to connect to other
applications, as well as to provide a certificate for other applications to connect. The following functions
must be covered:
• Adding a root or intermediate certificate to connect to the certificate store.
• Revoking a certificate
• Connect to one or more external certificate providers. This will give a company the possibility
to centrally manage equipment certificates.

Implementation details for these functionalities are responsibility of each equipment manufacturer but
should be documented for certification.

The client systems MUST support both Online Certificate Status Protocol (OCSP) and Certificate
Revocation List (CRL) for online certificate verification. In case of CRL repository or OCSP Server not
being available, the implementer should be capable of determining if soft fail (assume the certificate
has not being revoked) is allowed or not.

OCSP and hard fail must be enforced in the case that:

If you are legally obliged to enforce the certificate and certificate chain.
If the CRL grows indiscriminately or there is no one to maintain it.

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 20 of 34

At the time of writing, CRLSet as proposed by Google for CRL distribution and offline certificate
verification is still not mature enough to be included in this standard.

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 21 of 34

9 Application Authentication and Authorization

The following Authentication methods must be supported for every IFSF compliant API:
 No user authentication
 User and Password authentication
 API key

Additionally, any IFSF compliant API may implement OAuth 2.0 for delegation of authentication
functions. This will enable that access to all APIs be managed centrally in the future. Although not
mandatory, applications connecting to a REST API are recommended to support API keys authentication
over OAuth 2.0 architecture, as APIs security can be enhanced to support OAuth security through third
party application packages.

Note: Using digest methods to secure user and password is not recommended, as using TLS will provide
better levels of security, with better encryption keys management processes.

9.1 Decoupling Authentication and Authorization from APIs

To provide a higher level of security and implementing advanced security features while keeping
security implementation and management processes unified for all implemented APIs, the
implementer can deploy a central security management application.

There are off the shelf API manager software applications that can provide security services, including:
 OAuth security
 Token based security
 End to end encryption with TLS
 Rate limiting
 Centralized administration
 Monitoring tools
 Revocation policies, etc.

Currently there are both open source and enterprise grade applications that provide these
functionalities.

An API manager software application adds security to an unsecured API by exposing new secured
endpoints to API clients and, once properly authorized, forwarding the request to the unsecured API,
as depicted in the figure below:

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 22 of 34

Using API managers to secure resources

Note: Although the API manager can add security to an unsecured API, it will not resolve the injection
of security into the client.

Implementing advanced security features within APIs is not recommended due to:
 Software development complexity
o Cost of development
o Time of implementation
o Need of specialized development professionals
o High testing complexity
o High certification complexity
 Cost of Support over a large variety of systems.
 Permanent need to update security to keep up to date throughout time.
o Security algorithms are permanently deprecated due to detected vulnerabilities (E.G.
DES)

9.2 Using no Authentication

The implementing parties can optionally disable all authentication methods, hence providing access
with no authentication whenever the implementer deems it unnecessary, as the infrastructure is
already secure, or if they delegate access authentication and authorization to an external application
as explained above.

9.3 Using User and Password to Authenticate Users

To request access using a user and password combination, the client application must include in the
header a string containing user and password separated by a colon encoded in base64. Base64
encoding will not provide any level of encryption. Encryption can be achieved by using TLS 1.2 as
recommended in the part 2.3 standard document.

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 23 of 34

Example request:

Username= “IFSFClient”
Password= “pleaseGiveMeAccess”
Access Token: BASE64 ("IFSFClient:pleaseGiveMeAccess”):
SUZTRkNsaWVudDpwbGVhc2VHaXZlTWVBY2Nlc3M=

Submitted request:

POST /ifsf-fdc/v2/sites
Host: api.ifsf.org
Authorization: Basic SUZTRkNsaWVudDpwbGVhc2VHaXZlTWVBY2Nlc3M=
Content-Type: charset=UTF-8
Body Payload

9.4 Using API Keys to Authenticate Access

To request access using an API KEY, the client application must include in the header a string containing
the API key value. Base64 encoding is not required in this case, as API keys are designed not to require
encoding. As in the case of basic security, encryption can be achieved by using TLS 1.2 as recommended
in the part 2.3 standard document.

Note: Moving the API Key into the Authentication header works around allows much more efficient
caching. The HTTP Spec states that, "A shared cache MUST NOT use a cached response to a
request with an Authorization header field (Section 4.1 of [Part7]) to satisfy any subsequent
request unless a cache directive that allows such responses to be stored is present in the
response". This will avoid cache servers sending the same response to other applications, unless
the response contains the following directive: Cache-Control: public, enforcing cache servers
to cache the response for further API clients.

Example request:

API KEY= “IFSFClientAbc123”

Submitted request:

POST /ifsf-fdc/v2/sites
Host: api.ifsf.org
Authorization: apikey IFSFClientAbc123
Content-Type: charset=UTF-8
Body Payload

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 24 of 34

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 25 of 34

9.5 Using OAuth2.0 to authenticate API keys

API Keys over Oauth2.0 can be used to authenticate communications between equipment.

The API key will perform application only authorization. When using API key authorization please keep
in mind the following:

Tokens are passwords:

Keep in mind that the consumer key & secret, bearer token credentials, and the bearer token
itself grant access to make requests on behalf of an application. These values should be
considered as sensitive as passwords and must not be shared or distributed to untrusted
parties. The implementer must define proper ways to store and distribute these tokens.
TLS is mandatory during token negotiation:
This authentication method is only secure if TLS is used. Therefore, all requests (to both obtain
and use the tokens) must use HTTPS endpoints.
No user context
When issuing requests using application-only auth, there is no concept of a “current user.”

The application-only auth flow follows these steps:

• An application encodes its consumer key and secret into a specially encoded set of credentials.
• An application makes a request to the POST oauth2 / token endpoint to exchange these
credentials for a bearer token.
• When accessing the REST API, the application uses the bearer token to authenticate.
• The server will manage access to the corresponding entity and verb depending on the token
received.

9.5.1 Encoding consumer key and secret

The steps to encode an application’s consumer key and secret into a set of credentials to obtain a
bearer token are:

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 26 of 34

• URL encode the consumer key and the consumer secret according to RFC 1738. Note that at
the time of writing, this will not actually change the consumer key and secret, but this step
should still be performed in case the format of those values changes in the future.
• Concatenate the encoded consumer key, a colon character “:”, and the encoded consumer
secret into a single string.
• Base64 encode the string from the previous step.

Below are example values showing the result of this algorithm.

RFC 1738 encoded

xvz1evFS4wEEPTGEFPHBog
consumer key
RFC 1738 encoded
L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg
consumer secret
Bearer token xvz1evFS4wEEPTGEFPHBog:L8qq9PZyRg6ieKGEKhZolGC0vJWL
credentials w8iEJ88DRdyOg
Base64 encoded
eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJnNmllS0dFS
bearer token
2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==
credentials

9.5.2 Obtain a bearer token

The value calculated in previous step must be exchanged for a bearer token by issuing a request to
POST oauth2 / token:

• The request must be an HTTP POST request.

• The request must include an Authorization header with the value of Basic <base64 encoded
value from step 1>.
• The request must include a Content-Type header with the value of application/x-www-form-
urlencoded;charset=UTF-8.
• The body of the request must be grant_type=client_credentials.

Example request (Authorization header has been wrapped):

POST /ifsf-fdc/v2/oauth2/token HTTP/1.1

Host: api.ifsf.org
Authorization: Basic eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJn
NmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length: 29

grant_type=client_credentials

If the request format is correct, the server will respond with a JSON-encoded payload:

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 27 of 34

Example response:

HTTP/1.1 200 OK
Status: 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 140

{"token_type":"bearer","access_token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAA"}

Applications should verify that the value associated with the “token_type” key of the returned object
is bearer. The value associated with the “access_token” key is the bearer token.

9.5.3 Authenticate API requests with a bearer token

The bearer token may be used to issue requests to API endpoints that support application-only auth.
To use the bearer token, construct a normal HTTPS request and include an Authorization header with
the value of Bearer <base64 bearer token value from step 2>. Signing is not required.
Example request (Authorization header has been wrapped):

GET /ifsf-fdc/v2/sites/country=UK?count=100&limit=10 HTTP/1.1

Host: api.ifsf.org
Authorization: Bearer
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAA
AAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Accept-Encoding: gzip

10 Use-cases
10.1 Accessing a resource

A few examples of REST calls are listed below:

http://api.ifsf.org/ifsf-wsm/v1/countries
http://api.ifsf.org/ifsf-fdc/v2/sites/12345/tlgs/1/tps/4
http://api.ifsf.org/ifsf-fdc/v2.01/sites/12345/dsps/3/fps/1

The following use cases present some examples on how to invoke REST services.

In colors, each part of the URI is defined as:

• In red, the mechanism to access the resource. In this case, just http or https will be used.
• In blue, the specific computer that the resource is housed in. In this case, all the resource are
located in api.ifsf.org/, and there are two applications: a forecourt device controller and a wet
stock management application, where WSM is offering version 1 and FDC versions 2 and 2.01.
• In green, the specific name of the resource. It has several components:
o The resource itself (Settings, Tables)

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 28 of 34

o The group or super resource which it depends on

To get the settings of a given country (e.g. UK), the following command could be used:

GET http://api.ifsf.org/ifsf-wsm/v1/countries/UK/settings

The command above will return a representation of the settings for UK.

Now, to update the settings of a given country (e.g. UK), the following command could be used:

PUT http://api.ifsf.org/ifsf-wsm/v1/countries/UK/settings

The command above will update the representation of the settings for UK. The new representation will
be transferred through the HTTP Body.

10.2 Queries and filter

An IFSF compliant API should expose the information of the resource through GET HTTP verb, enabling
the client to include queries and filters.

Although query and filtering are more related to collections, there are three possible scenarios about
searching, detailed next.

10.2.1 Get a resource since the unique identifier

In this scenario, the clients need to get the representation of a resource, and he knows its unique
identifier.

In order to cover this use case, an IFSF compliant API should accept the unique identifier of a resource
as part of the URL, as expressed in the following example:

GET http://api.ifsf.org/ifsf-fdc/v1/sites/12345

This example will return the representation of the site which unique identifier is 12345.

10.2.2 Get a resource since a unique field, different to the unique identifier

Sometimes it may happen that the client does not know the unique identifier of a resource, but knows
the value of another field, that also uniquely identifies the resource. In this use case, the API should
accept a filter as a parameter in the querystring.

In the following example, the client does not know the unique identifier of a site (that is generated
internally for the host system), but knows the canonical name (field name) of the site (given by the
company, and known by everybody). This canonical name is unique among all sites, so it identifies
uniquely each one.

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 29 of 34

GET http://api.ifsf.org/ifsf-fdc/v1/sites?name=Raymond

This example will return a set containing a single element corresponding to the representation of the
site, with a canonical name (field name) of “Raymond”. The response is slightly different to the previous
use case where the client queries the element instead of the collection.

10.2.3 Get a resource (or a set of resources) using a combination of fields

The first and second scenarios was focused on getting a resource, but the most common use case is
querying for a set or resources, filtering its result using a set of parameters.

In this use case, the client of the API know some data about the resource, but not everything
(sometimes a functional category, the region to which a resource belongs, or another field).
The API, in order to cover this scenario, should accept a set of parameters as key-value pairs in the
query string, and should use it to filter the resultset.

To exemplify this case, we will suppose the site resource contains the attributes name, zone, company
and averageSalesAmount.

Given this resource, to get all the sites located in the zone “Boston”, and that belong to the company
“XYZ”, a client should use the following command:

GET http://api.ifsf.org/ifsf-fdc/v1/sites?zone=Boston&company=XYZ

Note that this command will return a set of resources.

The above cases only applies when the client needs to filter by an exact value, or a set of exact values.
If a client needs to get resource comparing a field with another operator different as equal (e.g. greater
than or less than), the API should accept an additional parameter following each filter name - filter value
pairs, called “op”, that will determine the comparison. The operators will be:
● LT, for “less than”
● GT, for “greater than”
● LET, for “less or equal than”
● GET, for “greater or equal than”
● EQ, for “equal”

If none operator is specified, “EQ” will be supposed.

Following the previous example, if a client should know the sites of the zone “Boston” that sell more
than 100.000 Pounds (field averageSalesAmount) greater than 100000, should use the following
command:

GET http://api.ifsf.org/ifsf-fdc/v1/sites?zone=Boston&averageSalesAmount
=100000#&op=GT

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 30 of 34

10.3 Sorting results

Results can be sorted by the client or by the server.

10.3.1 Client side

The client consumes an API, receiving the result set and sorting locally on the client-side. This is not
always an option since sorting may require significant resources (memory, processor, storage) that are
not available at the client side.

10.3.2 Server side

If an API designer wishes to offer a sorting mechanism, the API call MUST use the “sort” query
parameter. A list of comma separated fields can be specified in the criteria. The default sort order is
ascending. Descending sort order is indicated by a ‘-‘ field prefix.

For example, in the following request a client asks for the tank list for site 12345 sorted by product
ascending and by current volume descending:

GET http:// api.ifsf.org/ifsf-fdc/v1/sites/12345/tlgs/1/tanks?sort=product,-

currentVolume

10.4 Bulk operations

If an API designer wishes to offer bulk operations for creation, deletion or update of multiple resources,
the server must be prepared to process the request operation asynchronously, following the rules set
forth in the “Asynchronous Calls” section.

For example, if a client should create 3 sites, the command could be the following:

POST http://api.ifsf.org/ifsf-fdc/v1/sites
sites = [
{
“Zone”:”1”,
“Company”:”AAA”,
“name”:”Raymond”,
“averageSalesAmount”:”10000”,
“pbl”:”13579”
},
{
“Zone”:”1”,
“Company”:”AADA”,
“name”:”Twickenham”,
“averageSalesAmount”:”80000”,
“pbl”:”22222”
},
{
“Zone”:”1”,
“Company”:”AABBA”,

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 31 of 34

“name”:”Wimbledon”,
“averageSalesAmount”:”110000”,
“pbl”:”12345”
}
]

NOTE: Bulk operations should only be accepted when the command is specified to support this way
of processing in the application documentation.

10.5 Paging the results

Some IFSF API requests might offer results paging. The way to include pagination details is using the
Link header introduced by RFC 5988.

For example
GET http://api.ifsf.org/ifsf-fdc/v1/sites?zone=Boston&start=20&limit=5

The response should include pagination information in the Link header field as depicted below

{
“start”: 1,
“count”: 5,
“totalCount”: 100,
“totalPages”: 20,
“links”: [
{
“href”: “http://api.ifsf.org/ifsf-fdc/v1/sites?zone=Boston&start=26&limit=5”,
“rel”: “next”
},
{
“href”: “http://api.ifsf.org/ifsf-fdc/v1/sites?zone=Boston&start=16&limit=5”,
“rel”: “previous”
}
]
}

To implement this, two parameters will be accepted:

 start=id specifies the unique identifier of the expected first element in the result set. If the
element is not found in the result set, the server will respond 410 GONE. This parameter is used
to make sure that elements are not skipped or repeated while paging through the result set.

 limit=maxElements specifies the maximum number of elements per page (1..500).

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 32 of 34

For instance, if a client should know the sites of the zone “Boston”, but in subsets of 5 elements, should
use the following command:

GET http://api.ifsf.org/ifsf-fdc/v1/sites?zone=Boston&limit=5

This command returns just the first 5 elements. As the initial resource is not specified, the result will
contain the first subset of 5 elements and the link to the next subset.

{
“start”: 1,
“count”: 5,
“totalCount”: 100,
“totalPages”: 20,
“links”: [
{
“href”: “http://api.ifsf.org/ifsf-fdc/v1/sites? zone=Boston&start=6&limit=5”,
“rel”: “next”
}
]
}

The header should contain a link to the previous and next subset, using link headers. If a subset contains
the first element in the complete result set, the header will not contain a “previous” link. The first and
last subsets will not have a “previous” and “next” link, respectively.

To request the next five elements, the command should be:

GET http://api.ifsf.org/ifsf-fdc/v1/sites?zone=Boston&start=6&limit=5

The response will contain the following header:

{
“start”: 6,
“count”: 5,
“totalCount”: 100,
“totalPages”: 20,
“links”: [
{
“href”: “http://api.ifsf.org/ifsf-fdc/v1/sites?zone=Boston&start=11&limit=5”,
“rel”: “next”
},
{
“href”: “http://api.ifsf.org/ifsf-fdc/v1/sites?zone=Boston&limit=5”,
“rel”: “previous”
}
]

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 33 of 34

In the case site 6 was deleted, a 410 GONE error will be returned and the initial entity should be
requested again.

10.6 Asynchronous calls

When a client sends a request, the server response might not be available immediately. The server can
decide to process the request asynchronously. In this case, the server will return HTTP 202 ACCEPT,
create a job resource and return the job resource URL which can be used to query the job state.

If the client queries the job state and the job has been completed, the server will return the API call
response to the client and delete the job resource from the server.

If the API request header includes a callback address and the job is executed asynchronously and the
job has been completed, the server will try to deliver the response using the callback address. If the
callback was successful, the job will be deleted from the server. If the server was unable to reach the
client via callback, the server will not retry the callback. The client can still query the job state using the
job URL.

The server must internally define a job queue size limit and a job queue garbage collection policy for
queue maintenance.

Since the client cannot choose server-side synchronous or asynchronous execution, it must be prepared
for both scenarios in all API calls that support the response 202 Accepted in its specification.

In the following example, a client requests a set of sites that meet a certain condition. The server
calculates the SQL execution plan, decides it will take 30 seconds to calculate the result set, and decides
to process the request asynchronously. The command could be similar to this:

GET http://api.ifsf.org/ifsf-fdc/v1/sites?some-query-parameters

In this case, the response of the server would not be 200 (for GET) or 201 (for PUT or POST). The server
response will be 202 (Accepted) and the body of the response a URL that points to a queue to get the
information when ready:

HTTP/1.1 202 Accepted

Location: /queue/123456

The client can query the job URL for the job state. If the client queries the job state, while the request
is running, the client will receive HTTP 303 SEE OTHER.

We recommend the server assign expiration TTL to all queued jobs, and expire them regardless the
completion status. This will allow the server to limit how long (maximum) any given task can live in the
queue. Such a strategy is not contrary to the HTTP 202 Accepted declared purpose, and it is allowed for
a resource to never come to existence.

This document is Intellectual property of IFSF

 Revision / Date: Page:
PART 2.03 COMMUNICATIONS SPECIFICATIONS OVER REST
Vers. 1.1 (DRAFT) / Dec.2016 34 of 34

11 REST Backwards Compatibility

No backwards compatibility is considered, as the REST framework is substantially different from
previous RPC paradigm, where all calls use standard verbs on resources instead of identifying processes.
In addition, JSON will be used instead of XML to represent objects.

In order to reduce adoption costs, resources will maintain its attributes and attributes naming
convention whenever possible.

This document is Intellectual property of IFSF