Study on Safe and Secure

Parking Places for Trucks

MOVE/C1/2017-500

API Design Guidelines

mmmll
 Safe and Secure Truck Parking Study, API Design Guidelines

Report title:

STUDY ON SAFE AND SECURE PARKING PLACES FOR TRUCKS

API Design Guidelines

Reference: DG-MOVE Reference: MOVE/C1/2017-500

Date: June 19, 2018

2
 Safe and Secure Truck Parking Study, API Design Guidelines

Foreword .................................................................................................................................... 5

1. Context and architecture.................................................................................................... 6

1.1. Web services................................................................................................................... 6

2. Functional requirements .................................................................................................... 7

2.1. Discovery ........................................................................................................................ 7
2.2. Parking information and rating ...................................................................................... 7
2.2.1. List of available facilities / services............................................................................. 8
2.3. User management and profile........................................................................................ 9
2.3.1. User registration ......................................................................................................... 9
2.3.2. User login .................................................................................................................... 9
2.3.3. Password reset ........................................................................................................... 9
2.3.4. Delete account............................................................................................................ 9
2.4. Booking ........................................................................................................................... 9
2.4.1. Booking request........................................................................................................ 10
2.4.2. Booking confirmation ............................................................................................... 10
2.5. Payment, cancellation and refunds .............................................................................. 10
2.6. User-generated content ............................................................................................... 10
2.7. Social features .............................................................................................................. 11
2.8. Driving time monitoring ............................................................................................... 11

3. Non-functional requirements ........................................................................................... 11

3.1. Protocols and Data formats.......................................................................................... 11
3.2. Security ......................................................................................................................... 11
3.3. Information accuracy and reliability............................................................................. 12
3.4. Authentication and authorisation ................................................................................ 12
3.5. Documentation ............................................................................................................. 12

4. General API design guidelines .......................................................................................... 12

4.1. HTTP response status codes ......................................................................................... 12
4.2. Versioning ..................................................................................................................... 13
4.2.1. URI Versioning .......................................................................................................... 13
4.2.2. Custom Request Header ........................................................................................... 13
4.2.3. Accept header........................................................................................................... 13

3
 Safe and Secure Truck Parking Study, API Design Guidelines

4.3. Security ......................................................................................................................... 14

4.3.1. Keep it Simple ........................................................................................................... 14
4.3.2. Always Use HTTPS..................................................................................................... 14
4.3.3. Use Password Hash................................................................................................... 14
4.3.4. Never expose information in URL............................................................................. 14
4.3.5. Consider OAuth ........................................................................................................ 15
4.3.6. Consider Adding Timestamp in Request .................................................................. 15
4.3.7. Input Parameter Validation ...................................................................................... 15
4.4. Resources(nouns) not actions or verb.......................................................................... 15
4.5. Searching, sorting, filtering and pagination ................................................................. 15
4.5.1. Searching .................................................................................................................. 15
4.5.2. Sorting....................................................................................................................... 16
4.5.3. Filtering ..................................................................................................................... 16
4.5.4. Pagination ................................................................................................................. 16
4.6. HTTP methods .............................................................................................................. 16
4.7. Field name casing convention ...................................................................................... 16
4.8. Sub-resources for relations .......................................................................................... 16

5. Operational recommendations ........................................................................................ 16

5.1. Governance: updates and versioning ........................................................................... 16

6. Conclusion ........................................................................................................................ 17

4
 Safe and Secure Truck Parking Study, API Design Guidelines

Foreword
These guidelines are targeted at Safe and Secure parking providers for designing
Application Programming Interfaces (APIs) through which their services will be provided
through mobile apps to other entities, for example online platforms and fleet management
services. The provided APIs should enable authorised users to search, list, view details and
availability, as well as book, rate and comment on the parking areas.
In designing the API some general guidelines are recommended to be followed in order to
facilitate integration with back office systems, platforms and devices (e.g. smartphones),
and at the same time ensure its security and reliability and allow future updates. At the
same time the common approach to API design will also steer the way some user functions
are defined and thus enable a more seamless user experience regardless of app provider.

5
 Safe and Secure Truck Parking Study, API Design Guidelines

1. Context and architecture

Safe and Secure parking providers should enable access to their systems using approaches
common to other systems that make their services available over the Internet. An API is a
list of methods and classes exposed by a system or application which can be used by other
system or application to access their functionalities.

Parking service providers could make their service available for individual users and
enable them to search and book a parking space for a single vehicle, for example from a
mobile device (app), or also for users or systems (e.g. fleet management systems,
Enterprise resource planning – ERP…) that would make a booking for one or more
vehicles. To facilitate both kinds of interactions, for both use cases a single API design
should be used.

Making available an API designed according to certain guidelines should enable service
providers to make their services available through more channels and thus allow them
wider visibility and potential for more efficient use of their parking areas and finally higher
revenues.

1.1. Web services

Most usual way to provide services on the Internet is by using APIs in a form of web
services. In order for a developer to be able to make use of an API, the API needs to be
well documented. A web service is a type of API that is used over Hypertext Transfer
Protocol (HTTP). A web service is used for transferring machine-readable file/data formats
such as XML and JSON. Two of the most common web service types are Representational
State Transfer (REST) and Simple Object Access Protocol (SOAP).

A well-designed web service does not require substantial effort to integrate and provides a
secure access to system functionalities without exposing nor compromising its internal
functioning.

Some main characteristics* of a properly designed API can be summarised as follows:

6
 Safe and Secure Truck Parking Study, API Design Guidelines

• Easy to learn
• Easy to use, even without documentation
• Hard to misuse
• Easy to read and maintain code that uses it
• Sufficiently powerful to satisfy requirements
• Easy to extend
• Appropriate to audience

Furthermore, an API should be a result of a precise collection of requirements and

development of real-life use cases, needs to be platform independent and at the same time
it needs to be possible to evolve it in the future.

2. Functional requirements
This chapter elaborates the essential and optional functionalities that must to be provided
though the APIs in order to support the identified needs and requirements. In the future, the
need to add new functionalities might arise, therefore, the APIs need to have such
possibility without compromising existing users and integrations.

2.1. Discovery
Functionality provides listing of parking locations based on provided criteria. Several
filters can be added to the search criteria simultaneously, and the results shall be provided
as ordered lists. The supported search criteria shall include parking location characteristics
of various types, for example:

• location based on provided GPS coordinates and distance (radius),

• security rating (e.g. 1-5)
• comfort rating (e.g. 1-5)
• user rating
• included facilities
• price

2.2. Parking information and rating

Parking location details provided in a structured manner, with a mandatory set of
characteristics and a set of optional ones. The details shall support text, as well as other
media formats (e.g. photos).

Information that is mandatory:

• Location coordinates (GPS latitude and longitude)
• Address, postcode, country
• Phone number
• Parking capacity
• Currently available parking slots
• Price

Source:
https://static.googleusercontent.com/media/research.google.com/en//pubs/archive/32713.pdf

7
 Safe and Secure Truck Parking Study, API Design Guidelines

• Currency
• Security rating
• Comfort rating
• Last update (date)

Information that is optional:

• List of available facilities
• Available fuels
• User rating
• User comments

2.2.1. List of available facilities / services

The list of facilities or services available at a selected parking area needs to correspond to
an agreed and predefined (coded) categorisation of facilities in order to facilitate the
visualisation of the information in different languages. The services should also be listed
separately for drivers, vehicle or general.

The list shall include for example the following information:

Driver
• Restaurant / Coffee shop / buffet
• Hotel
• Toilets
• Showers
• Shop
• Lighting
• WiFi
• Medical first aid / assistance
• Cash machine (ATM)
• Camera surveillance
• Electric plugs
• Laundry

Vehicle
• Fuel
• Charging
• Snow and ice removal equipment
• Spare parts
• Mechanical assistance
• Vehicle wash

General
• Parking reservation and payment
• Capacity information
• Opening hours
• 24/7 security guard
• Camera surveillance

8
 Safe and Secure Truck Parking Study, API Design Guidelines

• Dangerous goods parking

• Oversized loads parking

2.3. User management and profile

The API needs to provide the means for managing user profiles. Besides supporting
registration and creation of a user profile, the API needs to provide a login mechanism with
authentication and authorisation and updating the user profile.

2.3.1. User registration

A new user shall be able to register to the system by providing his email address and
choosing a password. In addition, the user is required to provide a minimum set of personal
data. The minimum set of data should for example include the following data:

• Name
• Surname
• Languages spoken
• Organisation title
• Address and postcode
• Country
• VAT

Furthermore, the user shall be able to provide more information to complete his profile, for
example upload his photo, provide his interests and other ‘socially’ relevant information.

2.3.2. User login

The und user shall be able to login using his email address and the chosen password.

2.3.3. Password reset

The user shall be able to request the system to reset his password. In such case the system
shall send the user an email message with instructions on how to change the password.

2.3.4. Delete account

The user shall be able to delete his account and all related data. After the request the user
shall receive an email message where he is asked to confirm account deletion.

2.4. Booking
An authorised user shall be able to book a slot (or several) at a selected parking location.
Limits need to be defined, such as maximum booking duration, earliest booking date,
maximum arrival delay. After a booking request is made and payment is processed, the
API shall respond with a booking confirmation.

9
 Safe and Secure Truck Parking Study, API Design Guidelines

2.4.1. Booking request

A booking request requires the user to be authenticated and authorised and shall include
the following information:

• User (ID)
• Vehicle registration number
• Selected parking area
• Selected parking lot
• Desired parking start time (dd/mm/yyyy, hh:mm)
• Desired parking duration (in periods of 4, 12, 24 and 48 hours)
• Transport of dangerous goods (ADR, yes/no)
• Refrigerated (yes/no)
• Special requirements

2.4.2. Booking confirmation

After receiving a booking request and successfully processed payment, the system shall
respond with a booking confirmation. The confirmation shall include the following
information:

• User (ID)
• Booking ID
• Vehicle registration number
• Selected parking area
• Selected parking lot
• Parking start time (dd/mm/yyyy, hh:mm)
• Parking end time (dd/mm/yyyy, hh:mm)
• Latest parking arrival (dd/mm/yyyy, hh:mm)
• Transport of dangerous goods (ADR, yes/no)
• Special requirements
• Price paid

2.5. Payment, cancellation and refunds

Payment operations need to be provided through the API in order to support the booking
functionality. Here, sufficient level of security and stability and a vast support of payment
instruments need to be provided, together with a transparent process view (e.g. transaction
status, error codes, status notifications). Usually, the system is directed to an external
service, such as PayPal or similar in order to process the payment. Same system should
also provide refunds in certain cases.

2.6. User-generated content

API shall support user-generated content, from text to other media such as photo upload.
For example, the API could provide the following:

10
 Safe and Secure Truck Parking Study, API Design Guidelines

• Parking rating (e.g. satisfaction, information accuracy …)

• Commenting
• Photos upload
• Corrections to the information

2.7. Social features

This functionality, linked to user profiles and eventual social media channels shall enable
interaction between different users taking into account their characteristics (e.g.
nationality), current location or other preferences.
Some of the functionalities could include:

• Matching users of same nationalities, languages, interests

• Make friends
• Where to park / follow me (share booked parking info and location sharing)

2.8. Driving time monitoring

This additional functionality could assist drivers in managing their driving time based on
rest time provided by the booking information.

3. Non-functional requirements
This chapter details the recommended approach to designing an API in a way to ensure
easy integration, security, and use.

3.1. Protocols and Data formats

Most commonly used web service protocols are SOAP and REST, of which REST is more
lightweight and thus more suited also for mobile (smartphone) applications.

At the same time, the most common data formats are XML and JSON, of which JSON is
more lightweight and recommended to be used on mobile devices.

3.2. Security
For basic functionalities, which do not require user authentication (e.g. parking search),
there are no specific security requirements. For services that require user authentication
and allow for booking, payment, user generated content, as a basic requirement, the API
should use HTTP Secure (HTTPS) communication with Transport Layer (TLS)
encryption.

Furthermore, the payment API should adhere to the requirements and recommendations
defined by Payment Card Industry Data Security Standard (PCI DSS). Further details on
securing payments are available at:

11
 Safe and Secure Truck Parking Study, API Design Guidelines

https://www.pcisecuritystandards.org/pdfs/best_practices_securing_ecommerce.pdf?agree
ment=true&time=1499981509898

3.3. Information accuracy and reliability

The API shall provide up-to-date and accurate information on parking characteristics and
availability (except the information that relies on input from users for which the provider
cannot ensure accuracy and is not liable for).
The API shall also be provided with a high level or reliability. It is therefore recommended
that the provider uses state of the art equipment and services to ensure a high level of API
availability.

3.4. Authentication and authorisation

User authentication shall be done using methods common to other Internet services that
require similar level of security.
Two of the most common methods for authentication and authorisation are OAuth and API
Keys.
OAuth could be used at end-user level (e.g. app), whereas an API Key could be used when
a parking service is being booked by a back-office system (e.g. FMS, ERP).

3.5. Documentation
The API shall be supplemented by a comprehensive and clear documentation, ideally with
code samples, a detailed API reference section and sequence diagrams

4. General API design guidelines

This chapter brings forward the common approaches in designing APIs to ensure expected
API behaviour, security and efficiently support the identified functionalities.

4.1. HTTP response status codes

A RESTful API shall use appropriate HTTP response status codes. The most commonly
used are:

• 200 – OK
Indicates that the request has succeeded.
• 201 – CREATED
New resource has been created
• 204 – NO CONTENT
The resource was successfully deleted, no response body
• 304 – NOT MODIFIED
The date returned is cached data (data has not changed)
• 400 – BAD REQUEST
The request was invalid or cannot be served. The exact error should be explained in
the error payload. E.g. „The JSON is not valid “.

12
 Safe and Secure Truck Parking Study, API Design Guidelines

• 401 – UNATHORIZED
The request requires user authentication.
• 403 – FORBIDDEN
The server understood the request but is refusing it or the access is not allowed.
• 404 – NOT FOUND
There is no resource behind the URI.
• 500 – INTERNAL SERVER ERROR
API developers should avoid this error. If an error occurs in the global catch blog,
the stack trace should be logged and not returned as a response.

4.2. Versioning
There is not a single recommendation on how to version the API. The following three
approaches are the most common:

4.2.1. URI Versioning

Using the URI is the most straightforward and most commonly used approach though it
violates the principle that a URI should refer to a unique resource. You are also guaranteed
to break client integration when a version is updated.

Example:

http://api.truckparking.com/v1
http://apiv1.truckparking.com

The version need not be numeric, nor specified using the “v[x]” syntax. Alternatives
include dates, project names, seasons or other identifiers that are meaningful enough to the
team producing the APIs and flexible enough to change as the versions change.

4.2.2. Custom Request Header

A custom header (e.g. Accept-version) allows you to preserve your URIs between versions
though it is effectively a duplicate of the content negotiation behavior implemented by the
existing Accept header.

Example:

Accept-version: v1
Accept-version: v2

4.2.3. Accept header

Content negotiation may let you to preserve a clean set of URLs but you still have to deal
with the complexity of serving different versions of content somewhere. This burden tends
to be moved up the stack to your API controllers which become responsible for figuring
out which version of a resource to send. The end result tends to be a more complex API as
clients have to know which headers to specify before requesting a resource.

13
 Safe and Secure Truck Parking Study, API Design Guidelines

Example:

Accept: application/vnd.example.v1+json
Accept: application/vnd.example+json;version=1.0

In real world, an API is never going to be completely stable. It’s important how this change
is managed. A well-documented and gradual deprecation of API can be an acceptable
practice for most of the APIs.

4.3. Security

The points below may serve as checklist for designing secure RESTful APIs.

4.3.1. Keep it Simple

Secure an API just how secure it needs to be. Every time you make the solution
unnecessarily more complex, you are also likely to leave a hole.

4.3.2. Always Use HTTPS

By always using SSL, the authentication credentials can be simplified to a randomly
generated access token that is delivered in the user name field of HTTP Basic Auth. It’s
relatively simple to use, and you get a lot of security features for free.

If you use HTTP 2, to improve performance – you can even send multiple requests over a
single connection, that way you avoid the complete TCP and SSL handshake overhead on
later requests.

4.3.3. Use Password Hash

Passwords must always be hashed to protect the system (or minimize the damage) even if
it is compromised in some hacking attempt. There are many such hashing
algorithms which can prove really effective for password security e.g. MD5, SHA,
PBKDF2, bcrypt and scrypt algorithms.

4.3.4. Never expose information in URL

Usernames, passwords, session tokens, and API keys should not appear in the URL, as this
can be captured in web server logs, which makes them easily exploitable.

Example:

14
 Safe and Secure Truck Parking Study, API Design Guidelines

https://api.domain.com/user-
management/users/%7Bid%7D/someAction?apiKey=abcd123456789

Above URL exposes API key. Such form of security should be avoided.

4.3.5. Consider OAuth

Though basic authentication is good enough for most of the APIs and if implemented
correctly, it’s secure as well – yet you may want to consider OAuth as well. The OAuth 2.0
authorization framework enables a third-party application to obtain limited access to an
HTTP service, either on behalf of a resource owner by orchestrating an approval
interaction between the resource owner and the HTTP service, or by allowing the third-
party application to obtain access on its own behalf.

4.3.6. Consider Adding Timestamp in Request

Along with other request parameters, you may add a request timestamp as HTTP custom
header in API request. The server will compare the current timestamp to the request
timestamp, and only accepts the request if it is within a reasonable timeframe (1-2 minutes,
perhaps).

This will prevent very basic replay attacks from people who are trying to brute force your
system without changing this timestamp.

4.3.7. Input Parameter Validation

Validate request parameters on the very first step, before it reaches to application logic. Put
strong validation checks and reject the request immediately if validation fails. In API
response, send relevant error messages and example of correct input format to improve
user experience.

4.4. Resources(nouns) not actions or verb

To describe the resources concrete and meaningful names shall be used instead of action
verbs.

4.5. Searching, sorting, filtering and pagination

4.5.1. Searching
A search is a sub-resource of a collection. As such, its results will have a different format
than the resources and the collection itself. This allows us to add suggestions, corrections,
and information related to the search.
Parameters are provided the same way as for a filter, through the query-string, but they are
not necessarily exact values, and their syntax permits approximate matching.

15
 Safe and Secure Truck Parking Study, API Design Guidelines

4.5.2. Sorting
Sorting the result of a query on a collection of resources. A sort parameter should contain
the names of the attributes on which the sorting is performed, separated by a comma.

4.5.3. Filtering
Filtering consists in restricting the number of queried resources by specifying some
attributes and their expected values. It is possible to filter a collection on several attributes
at the same time and to allow several values for one filtered attribute.

4.5.4. Pagination
It is necessary to anticipate the paging of your resources in the early design phase of your
API. It is indeed difficult to foresee precisely the progression of the amount of data that
will be returned. Therefore, we recommend paginating your resources with default values
when they are not provided by the calling client, for example with a range of values [0-25].

4.6. HTTP methods

HTTP methods GET, PUT, POST, DELETE shall be used for RESTful APIs.

4.7. Field name casing convention

This convention intends to emphasize the beginning of each word by making the first letter
uppercase. E.g. camelCase, currentUser, etc. Aside from debates about its readability, its
main drawback is to be ineffective in contexts which are not case sensitive.

4.8. Sub-resources for relations

An alternative to only using top-level resources is to use sub-resources to make the
relationships between resources more obvious to the API user, and to reduce dependencies
on keys inside the resource representation.

5. Operational recommendations
5.1. Governance: updates and versioning
API specifications and versioning should be managed and published by a trusted entity.
The specification should include examples and a tool for testing the API. Furthermore, best
practices and SDK could be created for further facilitation of integrations.

16
 Safe and Secure Truck Parking Study, API Design Guidelines

6. Conclusion
The present document is intended to assist parking service providers in designing and
developing their APIs in order to facilitate first of all development of user interfaces, such
as web and mobile (smartphone) apps, and secondly, integration with back office systems
such as fleet management systems, ERP and such.
The actual implementation is left to the parking service provider, and the present
guidelines should at least make the work of those implementing the API easier, and at the
same time help preserve parking system security and integrity.
The work could be complemented with an actual recommendation, or a reference model of
an implementation of such API. In order to create such model, several existing APIs would
need to be analysed and a solution that takes into account all relevant functionalities should
be presented. Such reference model would even more facilitate business uptake of smaller
parking service providers by lowering the cost and implementation time.

***

17