ISO 20078-2:2021

Road vehicles - Extended vehicle (ExVe) web services - Part 2: Access

This document defines how to access resources on a web-services interface of an offering party using the Hypertext Transfer Protocol Secure (HTTPS). Resources can be accessed through request/reply and/or requested to be pushed. The Representational State Transfer (REST) architectural pattern is chosen as a common way to format resource paths both for request/reply and push. Some specific extensions to this pattern are defined to allow for asynchronous resource requests, such as, for example, forcing readouts of data from a connected vehicle.

Véhicules routiers — Web services du véhicule étendu (ExVe) — Partie 2: Accès

General Information

• Status: Published
• Publication Date: 29-Nov-2021
• ICS: 43.040.15 - Car informatics. On board computer systems
• Technical Committee: ISO/TC 22/SC 31 - Data communication
• Drafting Committee: ISO/TC 22/SC 31/WG 6 - Extended vehicle/Remote diagnostics
• Current Stage: 6060 - International Standard published
• Start Date: 30-Nov-2021
• Due Date: 06-Dec-2021
• Completion Date: 30-Nov-2021

Relations

• Revises: ISO 20078-2:2019 - Road vehicles - Extended vehicle (ExVe) web services - Part 2: Access
• Effective Date: 23-Apr-2020

Overview

ISO 20078-2:2021 - "Road vehicles - Extended vehicle (ExVe) web services - Part 2: Access" defines how an accessing party securely accesses resources on an offering party’s web‑services interface for connected vehicles. The standard mandates use of secure HTTP (HTTPS/TLS) and adopts the Representational State Transfer (REST) architectural pattern for resource paths. It specifies both synchronous request/reply and asynchronous push interaction patterns, including extensions to support asynchronous readouts (e.g., forcing data readouts from a connected vehicle).

Key technical topics

• REST-based web services over HTTPS with TLS (transport security) and HTTP/1.1+ compatibility.
• Interaction patterns:
  • Request/reply (recommended): client requests resource via HTTP GET/POST, server responds.
  • Push: offering party pushes resources to accessing party; includes subscription initiation and confirmation.
  • Push with subsequent request/reply: push of a reference followed by a fetch.
• Resource model and URIs:
  • Resources exposed as plural-noun collections and uniquely identified by URIs (e.g., {base_URI}/vehicles/{vehicleId}/...).
  • Base URI definition and compatibility with ExVe application resource paths.
• Subscription profiles and reusable subscription information for push delivery.
• Container management API and OpenAPI specifications (Annex A, B, C).
• Operational controls and quality aspects addressed in the standard:
  • Resource versioning
  • Rate limits
  • HTTP methods and response status codes
  • Error messaging and interaction patterns (asynchronous handling)
  • Media types and HTTP header fields
• Normative references include ISO 20078-1 (Content and definitions), ISO 8601 (date/time), and links to OpenAPI artifacts.

Key requirements (examples)

• REQ_04_01_01: Interface shall use HTTPS with TLS.
• REQ_04_01_02: HTTP shall be version 1.1 or higher.
• REQ_04_01_03: TLS shall be 1.2 or higher.
• REQ_04_01_05: Request/reply REST implementation shall be stateless.
• REQ_04_02_02: Exposed resources shall be uniquely identified by URIs. (These are representative requirement identifiers from the standard.)

Practical applications and who uses it

ISO 20078-2 is targeted at organizations building and operating connected vehicle ecosystems:

• Vehicle manufacturers (OEMs) designing ExVe server endpoints.
• Telematics service providers and backend platform architects.
• Tier‑1 suppliers implementing ECU/vehicle data exposure.
• Fleet operators and telematics integrators consuming vehicle data securely.
• Security and API teams specifying access control, rate limiting, and asynchronous workflows for vehicle data.

Adopting ISO 20078-2 helps ensure interoperable, secure, and predictable access to vehicle resources for telemetry, diagnostics (DTC readouts), vehicle functions (lock/unlock), and other telematics services.

Related standards

• ISO 20078-1: ExVe content and definitions (normative for Part 2).
• ISO 20078-3: Authentication and authorization (related to access control).
• ISO 8601: Date and time representations used by the standard.

Standards Content (Sample)

INTERNATIONAL ISO
STANDARD 20078-2
Second edition
2021-11
Road vehicles — Extended vehicle
(ExVe) web services —
Part 2:
Access
Véhicules routiers — Web services du véhicule étendu (ExVe) —
Partie 2: Accès
Reference number
© ISO 2021
All rights reserved. Unless otherwise specified, or required in the context of its implementation, no part of this publication may
be reproduced or utilized otherwise in any form or by any means, electronic or mechanical, including photocopying, or posting on
the internet or an intranet, without prior written permission. Permission can be requested from either ISO at the address below
or ISO’s member body in the country of the requester.
ISO copyright office
CP 401 • Ch. de Blandonnet 8
CH-1214 Vernier, Geneva
Phone: [phone]
Email: [e-mail]
Website: www.iso.org
Published in Switzerland
ii
Contents Page
Foreword .iv
1 Scope . 1
2 Normative references . 1
3 Terms, definitions and abbreviated terms . 1
3.1 Terms and definitions . 1
3.2 Abbreviated terms . 1
4 Representational state transfer-based interface . 1
4.1 General . 1
4.1.1 Introduction . 1
4.1.2 Request/reply . 2
4.1.3 Push. 2
4.1.4 Push with subsequent request/reply. 4
4.1.5 Requirements . 6
4.2 Resources . 7
4.3 Subscription profiles . 11
4.4 HTTP header fields . 20
4.5 Media types . 21
4.6 Resource versioning . 21
4.7 Resources and web services . 22
4.7.1 General .22
4.7.2 Examples . 22
4.8 Rate limits . 23
4.9 HTTP methods . 24
4.10 HTTP response status codes .25
4.11 Error messaging . 26
4.12 Interaction pattern .29
4.12.1 Asynchronous .29
4.13 Resource discovery. 33
4.14 Capability discovery .34
5 Container management API .35
5.1 General . 35
5.2 Container management operations . 35
Annex A (informative) Container management API specification .45
Annex B (normative) Container management OpenAPI specification .64
Annex C (normative) OpenAPI specification for container push notifications .65
Bibliography .66
iii
Foreword
ISO (the International Organization for Standardization) is a worldwide federation of national standards
bodies (ISO member bodies). The work of preparing International Standards is normally carried out
through ISO technical committees. Each member body interested in a subject for which a technical
committee has been established has the right to be represented on that committee. International
organizations, governmental and non-governmental, in liaison with ISO, also take part in the work.
ISO collaborates closely with the International Electrotechnical Commission (IEC) on all matters of
electrotechnical standardization.
The procedures used to develop this document and those intended for its further maintenance are
described in the ISO/IEC Directives, Part 1. In particular, the different approval criteria needed for the
different types of ISO documents should be noted. This document was drafted in accordance with the
editorial rules of the ISO/IEC Directives, Part 2 (see www.iso.org/directives).
Attention is drawn to the possibility that some of the elements of this document may be the subject of
patent rights. ISO shall not be held responsible for identifying any or all such patent rights. Details of
any patent rights identified during the development of the document will be in the Introduction and/or
on the ISO list of patent declarations received (see www.iso.org/patents).
Any trade name used in this document is information given for the convenience of users and does not
constitute an endorsement.
For an explanation of the voluntary nature of standards, the meaning of ISO specific terms and
expressions related to conformity assessment, as well as information about ISO's adherence to
the World Trade Organization (WTO) principles in the Technical Barriers to Trade (TBT), see
www.iso.org/iso/foreword.html.
This document was prepared by Technical Committee ISO/TC 22, Road vehicles, Subcommittee SC 31,
Data communication.
This second edition cancels and replaces the first edition (ISO 20078-2:2019), which has been
technically revised.
The main changes are as follows:
— added definition of a push method, allowing the offering party to push resources to the accessing
party according to subscription;
— added definition of reusable subscription profiles, used to store URI locations and authorization
information from the accessing party and used by offering party to push subscribed resources;
— defined requirements for container management API;
— added Annex A and digital Annex B describing container management API;
— revised error format;
— redefined resource versioning.
A list of all parts in the ISO 20078 series can be found on the ISO website.
Any feedback or questions on this document should be directed to the user’s national standards body. A
complete listing of these bodies can be found at www.iso.org/members.html.
iv
INTERNATIONAL STANDARD ISO 20078-2:2021(E)
Road vehicles — Extended vehicle (ExVe) web services —
Part 2:
Access
1 Scope
This document defines how to access resources on a web-services interface of an offering party using
the Hypertext Transfer Protocol Secure (HTTPS). Resources can be accessed through request/reply
and/or requested to be pushed.
The Representational State Transfer (REST) architectural pattern is chosen as a common way to format
resource paths both for request/reply and push. Some specific extensions to this pattern are defined
to allow for asynchronous resource requests, such as, for example, forcing readouts of data from a
connected vehicle.
2 Normative references
The following documents are referred to in the text in such a way that some or all of their content
constitutes requirements of this document. For dated references, only the edition cited applies. For
undated references, the latest edition of the referenced document (including any amendments) applies.
ISO 20078-1, Road vehicles — Extended vehicle (ExVe) web services — Part 1: Content and definitions
ISO 8601 (all parts), Date and time — Representations for information interchange
3 Terms, definitions and abbreviated terms
3.1 Terms and definitions
For the purposes of this document, the terms and definitions given in ISO 20078-1 apply.
ISO and IEC maintain terminological databases for use in standardization at the following addresses:
— ISO Online browsing platform: available at https:// www .iso .org/ obp
— IEC Electropedia: available at https:// www .electropedia .org/
3.2 Abbreviated terms
For the purposes of this document, the abbreviated terms given in ISO 20078-1 apply.
4 Representational state transfer-based interface
4.1 General
4.1.1 Introduction
There are three different ways to access resources for the accessing party, request/reply, push, and
push with a subsequent request/reply. Request/reply is the recommended method, but push can be
used when needed. In most cases only one method is used for a particular resource, but sometimes both
request/reply and push are needed. Latency, message size and frequency are examples of requirements
to consider when selecting between request/reply, push, and push with subsequent request/reply.
4.1.2 Request/reply
Figure 1 shows an example of request/reply sequence, where the accessing party requests a resource
using HTTP GET and the offering party returns it in the payload.
Figure 1 — Request/reply example
4.1.3 Push
Figure 2 shows an example of push sequence, where the accessing party initiates a push of a resource
using HTTP POST. The offering party confirms the subscription and starts to push the resource using
HTTP POST. Figure 2 shows an example where the push is done two times.
Figure 2 — Push example
Figure 3 shows an example of push sequence, where there is no explicit initiation of the push from the
accessing party. It is instead initiated by for instance rules or configuration at the offering party. It is
outside the scope of this document to describe how this is agreed between the accessing party and the
offering party.
Figure 3 — Push example without explicit initiation
4.1.4 Push with subsequent request/reply
Figure 4 shows an example of push with subsequent request/reply, where the accessing party initiates
a push of a resource using HTTP POST. The offering party confirms the subscription and starts to push
the resource reference using HTTP POST. The accessing party uses the resource reference to request
the resource from the offering party.
Figure 4 — Push with subsequent request/reply example
Figure 5 shows an example of push with subsequent request/reply, where there is no explicit initiation
of the push from the accessing party. It is instead initiated by, for instance, rules or configuration at
the offering party. It is outside the scope of this document to describe how this is agreed between the
accessing and the offering party.
Figure 5 — Push with subsequent request/reply example without explicit initiation
4.1.5 Requirements
[9] [6][7]
The following defines the requirements on a REST -based web service interface using HTTPS
based on transport layer security (TLS) to give the accessing party secure access to resources provided
by the offering party. The requirements in this document are valid both for request/reply and push
unless otherwise stated.
REQ_04_01_01 The REST-based web services interface implementation shall use HTTPS as the
transport protocol with TLS.
REQ_04_01_02 HTTP shall only be used with version 1.1 or higher compatible versions.
REQ_04_01_03 TLS shall only be used with version 1.2 or higher versions.
REQ_04_01_04 The request/reply REST web service shall be a strict client-server interaction,
where the accessing party (client) sends a request and the offering party (server)
sends a response.
NOTE Resources can be transferred both in the request and the response.
REQ_04_01_05 The request/reply REST implementation shall be stateless; i.e. the offering party
server shall not maintain any accessing party client context or session information.
Due to REQ_04_01_05, each request-response pair is handled independently from one another. Each
client request by the accessing party contains all information required by the server of the offering
party to successfully respond to the request, including a representation of the client state when
necessary.
REQ_04_01_06 A push initiation REST web service shall be a strict client-server interaction, where
the accessing party (client) sends a request and the offering party (server) sends a
response.
REQ_04_01_07 The push REST web service shall be a strict client-server interaction, where the
offering party (client) sends a request and the accessing party (server) sends a
response.
4.2 Resources
REQ_04_02_01 Information on the server shall be exposed as resources expressed as plural nouns.
NOTE 1 This holds true even when the resource is only available one time on a connected vehicle (e.g.
"odometers").
REQ_04_02_02 The exposed resources shall be uniquely identified in the form of Uniform Resource
Identifiers (URIs).
The resources, the resource groups or the containers, and how to apply those on a specific presentation
or application layer of the accessing party are described in ISO 20078-1. How an accessing party
authenticates and how it is authorized for access to resources is described in ISO 20078-3.
REQ_04_02_03 The offering party shall define the base URIs of the web services offered by the
offering party.
Table 1 — Examples of possible ExVe-based URIs
Resource Description
https:// {example .com}/ exve/ URI based on sub directory
https:// exve .{example .com}/ URI based on sub domain
REQ_04_02_04 The offering party shall comply with the URI resource paths defined by specific
ExVe standard applications.
Table 2 — Examples of possible ExVe resource URIs
Resource Description
{base_URI}/{resourcePath} Resources based on path
{base URI}/vehicles A list of the available vehicles as defined by
authorization context
{base URI}/vehicles/{vehicleId}/dtcReadouts/ Read all Diagnostic Trouble Codes for a spe-
cific vehicle
{base URI}/vehicles/{vehicleId}/ecus/{ecuId}/dtcReadouts/ Read all Diagnostic Trouble Codes for a spe-
cific ECU of a specific vehicle
There are two primary elements defining an URI: entities and resources (Table 2). Entities are the
fundamental objects representing, e.g. vehicles, ECUs, drivers and fleets. Resources are the actual data,
aggregated information or functionalities associated with an entity and a specific use case.
REQ_04_02_05 Resources shall be named and described.
EXAMPLE Fuel level can be an example of a single data item resource, vehicle position can be an aggregated
resource consisting of several data items (e.g. latitude, longitude, sample time) and lock and unlock the vehicle
can be a functionality resource.
REQ_04_02_06 The offering party should have the possibility to extend resources, but shall not be
able to reduce resources.
Thus, by REQ_04_02_06 it is not possible to remove data items from a resource, other than through an
update of the underlying use case specification. It is however possible to add data items to a resource
(i.e. versioning).
REQ_04_02_07 Aggregated resources shall only include or cross-reference necessary data items
for the complete and correct operation of the related use case.
NOTE 2 REQ_04_02_07 ensures an accessing party only receives data items necessary for fulfilling the
intended need and nothing else when accessing the resource (i.e. data economy).
See also ISO 20078-1:2021, 8.3, for further details.
REQ_04_02_08 A resource within an already existing use case should not be redefined.
An application may extend the recommended patterns below if none of them meets the needs of the use
case.
REQ_04_02_09 Each use case shall define how the HTTP operations GET, POST, PUT, PATCH, and
DELETE are supported for each defined resource and what the response for each
operation is.
REQ_04_02_10 All URI elements shall be written in lower camel case notation.
NOTE 3 The {baseURI} in following patterns refers to the offering party root URI (see Table 3).
Table 3 — Examples of base URI expresses REQ_04_02_09 and REQ_04_02_01
Normative generic format {baseURI}/{entities}
Example {baseURI}/vehicles
Request a list of all vehicles available to the accessing party.
REQ_04_02_11 Relations of entities shall be expressed using subresources.
NOTE 4 See Table 4.
Table 4 — Examples of sub-URI’s expresses REQ_04_02_11 and REQ_04_02_01
Normative generic format {baseURI}/{entities}/{ID}/{entities2}/{ID2}
Example {baseURI}/fleets/12/vehicles/456
Request information on vehicle with id 456 of fleet with id 12.
{baseURI}/vehicles/456/ecus/789
Request information on ECU with id 789 of vehicle with id 456.
REQ_04_02_12 A resource shall be placed after the entity to which it belongs in the URI.
NOTE 5 See Table 5.
Table 5 — Examples of descriptive URI’s expresses REQ_04_02_12 and REQ_04_02_01
Normative generic format {baseURI}/{entities}/{ID}/{resource}
Example {baseURI}/vehicles/123/positions
Request all positions for vehicle with id 123.
{baseURI}/vehicles/456/odometers
Request the odometer value for vehicle with id 456.
{baseURI}/vehicles/456/tirePressures
Request tire pressures of all wheels on the vehicle with id 456.
REQ_04_02_13 If filtering of the response is needed, query parameters shall be used.
NOTE 6 Several query parameters can be added to a request.
NOTE 7 See Table 6.
Table 6 — Examples of filtering responses expresses REQ_04_02_13 and REQ_04_02_01
Normative generic format {baseURI}/{entities}?{filter}={filterValue}
{baseURI}/{entities}?{filter}={filterValue}&{filter2}={filterValue2}
Example {baseURI}/vehicles?ignitionState=on
Request all vehicles with ignition on.
{baseURI}/vehicles/123/positions?startDate=.&endDate=.
Request the positions for vehicle with id 123 registered in given date span in
the ISO 8601 series date-time format.
REQ_04_02_14 If sorting is needed, query parameters shall be used.
NOTE 8 See Table 7.
Table 7 — Examples of query parameters expresses REQ_04_02_14 and REQ_04_02_01
Normative generic format {baseURI}/{entities}?{sorting}={sortingValue}
{baseURI}/{entities}?{sorting}={sortingValue}&{sorting2}={sortingValue2}
Example {baseURI}/vehicles?sortField=id&sortOrder=asc
REQ_04_02_15 If selection of subsets of resources is needed, query parameters shall be used.
NOTE 9 See Table 8.
Table 8 — Examples of query parameters for subsets expresses REQ_04_02_15 and
REQ_04_02_01
Normative generic format {baseURI}/{entities}?{id}={ID}
{baseURI}/{entities}?{id}={ID}&{id2}={ID2}
Example {baseURI}/vehicles?id=123&id=124
{baseURI}/vehicles?id=YS2RX20001754836
Identifiers may come in multiple formats including, but not limited to, VIN or pseudonymized IDs.
REQ_04_02_16 Pseudonymized IDs may be simple numerical IDs, UUIDs or any other alphanumerical
scheme.
NOTE 10 See Table 9.
Table 9 — Examples of pseudonymized IDs represented by numerical IDs expresses
REQ_04_02_16 and REQ_04_02_01
Normative generic {baseURI}/{entities}?{id}={ID}
format
{baseURI}/{entities}?{id}={ID}&{id2}={ID2}
Example {baseURI}/vehicles?id=ce5d5e3d-28bc-475f-8ef7-b5cb9c8039d4&id=f95ce756-42fc-
48b2-8873-86553f6df5cc
{baseURI}/vehicles?id=456
REQ_04_02_17 For large resource responses pagination may be used.
NOTE 11 See Table 10.
Table 10 — Examples of pagination expresses REQ_04_02_17 and REQ_04_02_01
Normative generic format {baseURI}/{entities}?start={value}&limit={count}
Example {baseURI}/vehicles?start=20&limit=10
REQ_04_02_18 A GET request on the returned location may return the total amount of results. If
used, it shall be part of the message body using the keyword “exveTotal”.
EXAMPLE The following example expresses REQ_04_02_18:
{
"results": {
"exveTotal": "150",
… }
}
REQ_04_02_19 If wildcards are used, a wildcard (*) shall access all subentities or resources of all
parent entities.
NOTE 12 See Table 11.
Table 11 — Examples of wildcards in URIs expresses REQ_04_02_19 and REQ_04_02_01
Normative generic format {baseURI}/{entities}/*/{entities2}
Example {baseURI}/vehicles/*/positions
Request all positions for all vehicles.
{baseURI}/vehicles/*/ecus
Request all ECU’s of all vehicles.
REQ_04_02_20 If wildcards are used, a wildcard (*) may be combined with other filtering, includ-
ing IDs, to access a smaller number of entities.
NOTE 13 See Table 12.
Table 12 — Examples of wildcards in URIs while filtering by IDs expresses REQ_04_02_20 and
REQ_04_02_01
Normative generic {baseURI}/{entities}/*/{resource}?{id}={ID}&{id2}={ID2}&{filter}={filterValue}&{-
format filter2}={filterValue2}
Example {baseURI}/vehicles/*/odometers?id=456&id=789& startDate=.&endDate=.
Request all odometer values from vehicles with id 456 and 789 registered within the
given time span in the ISO 8601 series date-time format.
REQ_04_02_21 For fully anonymized access, no entity IDs shall be used in the URIs.
NOTE 14 See Table 13.
Table 13 — Examples of an anonymized access expresses REQ_04_02_21 and REQ_04_02_01
Normative generic format {baseURI}/{entities}/{entities2}
Example {baseURI}/vehicles/hazardWarnings?isActive=true
REQ_04_02_22 A push resource shall be suffixed with subscriptions.
NOTE 15 See Table 14.
Table 14 — Examples of push resources regarding REQ_04_02_22
Normative generic format {baseURI}/{resource}Subscriptions
Example POST {baseURI}/positionSubscriptions?vehicleId=123
Subscribe to positions for vehicle with id 123.
GET {baseURI}/positionSubscriptions
Request a list of all position subscriptions.
POST {baseURI}/vehicles/456/tirePressureSubscriptions?pressure=low
Subscribe to low tire pressures of all wheels on the vehicle with id 456.
REQ_04_02_23 The accessing party shall define the base URIs of the web services offered by the
accessing party. (Compare with REQ_04_02_03).
4.3 Subscription profiles
Push of subscribed resources requires URI locations and authorization information from the accessing
party. This information is stored in subscription profiles. Subscription profiles can be created in a
separate step before creating subscriptions or directly when creating a subscription. In both cases the
subscription profile will be assigned an id and can be reused by any number of subscriptions.
REQ_04_03_01 A subscription profile shall contain:
—  profileId (assigned at creation),
—  callback baseURI,
—  token information according to REQ_04_03_02 or REQ_04_03_03.
REQ_04_03_02 A subscription profile for refresh token shall contain:
—  an OAuth2 refresh token,
—  the OAuth2 refresh token lifetime,
—  the OAuth2 endpoint for renewing access tokens.
NOTE 1 See Table 15.
REQ_04_03_03 A subscription profile for bearer token shall contain:
—  a bearer token,
—  the bearer token lifetime.
NOTE 2 It is the responsibility of the accessing party to renew the subscription profile before the bearer token
expires.
NOTE 3 See Table 16.
REQ_04_03_04 A subscription shall contain a subscription profile.
REQ_04_03_05 The full subscription profile information can be provided when the subscription is
created.
Table 15 — Examples of REQ_04_03_05 providing subscription profile information for refresh
token
Normative generic format POST {baseURI}/{resource}Subscriptions
“profile:”
“token_type”:”refresh_token”
“token”:”{token}”
“expires_in”:{lifetime in seconds for refresh token}
“tokenEndpoint”:”{accessingPartyTokenEndpoint}”
“callbackBaseURI”:”{accessingPartyBaseURI}
Response:
HTTP 201
Location: {URI of created subscription}
Response payload: "profileId": "{Subscription profile id}"
Table 15 (continued)
Example POST {baseURI}/positionSubscriptions?vehicleId=123
{
“profile”:
{
“token_type”:”refresh_token”,
“token”:”VGhpcyBpcaCB0b2tlbiwg … cm1hdHRlZA==”,
“expires_in”: 31536000,
“tokenEndpoint”: “https:// oauth2 .example .com/ token”,
“callBackBaseURI”: “https:// ap .example .com/ exVe”
}
}
Subscribe to positions for vehicle with id 123.
Response:
HTTP 201 (created) response returns location header of the new subscription
resource (id 2233) and implicitly created subscription profile id in the response
body:
Location: {baseURI}/positionSubscriptions/2233
Response payload: {"profileId": "1234"}
Table 16 — Examples of REQ_04_03_05 providing subscription profile information for bearer
token
Normative generic format POST {baseURI}/{resource}Subscriptions
“profile:”
“token_type”:”bearer_token”
“token”:”{token}”
“expires_in”:”{lifetime in seconds for bearer token}”
“callbackBaseURI”:”{accessingPartyBaseURI}
Response:
HTTP 201
Location: {URI of created subscription}
Response payload: "profileId": "{subscription profile id}"
Table 16 (continued)
Example of subscription POST {baseURI}/positionSubscriptions?vehicleId=123
containing authorization
{
information and implicit
creation of subscription “profile”:
profile
{
“token_type”:”bearer_token”,
“token”:”VGhpcyBpcaCB0b2tlbiwg … cm1hdHRlZA==”,
“expires_in”:3600,
“callBackBaseURI”:”https:// ap .example .com/ exVe”
}
}
Subscribe to positions for vehicle with id 123.
Response:
HTTP 201 (created) response returns location header of the new subscription
resource (id 2234) and implicitly created subscription profile id in the response
body:
Location: {baseURI}/positionSubscriptions/2234
Response payload: {"profileId": "1235"}
REQ_04_03_06 A subscription profile id (profileId) can be provided when the subscription is
created.
NOTE 4 Subscription profiles can be managed by APIs or in web portals.
NOTE 5 See Table 17.
Table 17 — Examples of REQ_04_03_06 providing subscription profile id
Normative generic format POST {baseURI}/{resource}Subscriptions
“profileId”:{profileId}
Example POST {baseURI}/positionSubscriptions?vehicleId=123
“profileId”:”2233”
Subscribe to positions for vehicle with id 123, authorization information is pro-
vided in a profile with id 2233.
REQ_04_03_07 HTTP POST can be used by accessing party to create subscription profile for sub-
scriptions.
NOTE 6 See Table 18 and Table 19.
Table 18 — Examples of creating subscription profile for subscriptions regarding
REQ_04_03_02 and REQ_04_03_07
Normative generic format POST {baseURI}/subscriptionProfiles
“token_type”:”refresh_token”
“token”:”{token}”
“expires_in”:”{lifetime in seconds for refresh token}”
“tokenEndpoint”:”{accessingPartyTokenEndpoint }”
“callbackBaseURI”:”{accessingPartyBaseURI}
Example POST {baseURI}/subscriptionProfiles
Creates subscription profile for subscriptions
Request payload:
{ “token-type”=”refresh_token”,
“token”=”RThpcyBpcaCB0b2tlbiwg … cm1hdHRlZA==”,
“expires_in”=31557600,
“tokenEndpoint”=“https:// oauth2 .example .com/ token”,
“callBackBaseURI”=“https:// ap .example .com/ exVe”
}
HTTP 201 (created) response returns location header of the new resource:
Location: {baseURI}/subscriptionProfiles/2233
Table 19 — Examples of creating subscription profile for subscriptions regarding
REQ_04_03_03 and REQ_04_03_07
Normative generic format POST {baseURI}/subscriptionProfiles
“token_type”:”bearer_token”
“token”:”{token}”
“expires_in”:”{lifetime in seconds for bearer token}”
“callbackBaseURI”:”{accessingPartyBaseURI}
Table 19 (continued)
Example POST {baseURI}/subscriptionProfiles
Creates subscription profile for subscriptions
Request payload:
{ “token-type”=”bearer_token”,
“token”=”BThpcyBpcaCB0b2tlbiwg … cm1hdHRlZZ==”,
“expires_in”=3600,
“callBackBaseURI”=“https:// ap .example .com/ exVe”
}
HTTP 201 (created) response returns location header of the new resource:
Location: {baseURI}/subscriptionProfiles/3344
REQ_04_03_08 HTTP GET can be used by accessing party to request a list of subscription profiles.
NOTE 7 See Table 20.
Table 20 — Examples of requesting a list of subscription profiles regarding REQ_04_03_08
Normative generic format GET {baseURI}/subscriptionProfiles
Example GET {baseURI}/subscriptionProfiles
Request all available subscription profiles for an accessing party.
Response payload:
{“profiles” : [
{“profileId”=”2233”,
“token-type”=”refresh_token”,
“tokenExpTime”=1611999920,
“tokenEndpoint”=“https:// oauth2 .example .com/ token”,
“callBackBaseURI”=“https:// ap .example .com/ exVe”
},
{“profileId”=”3344”,
“token-type”=”bearer_token”,
“tokenExpTime”=1580417120,
“callBackBaseURI”=“https:// ap .example .com/ exVe”
}
]
}
[8]
Where tokenExpTime = (subscription time + expires_in) as a unix timestamp .
REQ_04_03_09 HTTP DELETE can be used by accessing party to delete a subscription profile.
NOTE 8 See Table 21.
Table 21 — Examples of deleting subscription profile regarding REQ_04_03_09
Normative generic format DELETE {baseURI}/subscriptionProfiles/{profileId}
Example DELETE {baseURI}/subscriptionProfiles/2233
Delete subscription profile with id=2233.
REQ_04_03_10 The offering party shall inactivate the subscription when the provided authoriza-
tion has expired.
REQ_04_03_11 The subscription shall be assigned a unique identifier called subscriptionID.
NOTE 9 See Table 22.
Table 22 — Example of subscriptionID regarding REQ_04_03_11
Normative generic format subscriptionID={unique identifier}
Example “subscriptionID”=”1eb16206-0179-4ade-b5ea-08b6e6b4ebd5”
REQ_04_03_12 If subscriptions are initiated explicitly, HTTP POST shall be used.
NOTE 10 See Table 23.
Table 23 — Example of subscription regarding REQ_04_03_12
Normative generic format POST {baseURI}/{resource}Subscriptions
Example POST {baseURI}/positionSubscriptions?vehicleId=123
Subscribe to positions for vehicle with id 123.
REQ_04_03_13 If subscriptions are initiated explicitly, updating a subscription shall be done using
HTTP PUT.
NOTE 11 See Table 24.
Table 24 — Examples of updating a subscription regarding REQ_04_03_13
Normative generic format PUT {baseURI}/{resource}Subscriptions/{subscriptionId}
Example PUT {baseURI}/positionSubscriptions/789
Update the position subscription with subscription id 789.
PUT {baseURI}/positionSubscriptions/567?addVehicleId=234
Extend the existing subscription (Subscription id 567) with positions for the vehi-
cle with id 234 (using query parameters).
Table 24 (continued)
PUT {baseURI}/positionSubscriptions/567
{“position” : [
{“vehicleId”=”234”},
{“action”:”ADD”} ]
}
Extend the existing subscription (Subscription id 567) with positions for the vehi-
cle with id 234 (using JSON payload).
REQ_04_03_14 If subscriptions are initiated explicitly, deleting a subscription shall be done using
HTTP DELETE.
NOTE 12 See Table 25.
Table 25 — Examples of deleting a subscription regarding REQ_04_03_14
Normative generic format DELETE {baseURI}/{resource}Subscriptions/{subscriptionId}
Example DELETE {baseURI}/positionSubscriptions/456
Delete the subscription for positions with subscription id 456.
REQ_04_03_15 The resource shall be pushed using HTTP POST to the baseURI decided by the
accessing party.
NOTE 13 See Table 26.
Table 26 — Examples of pushing resources regarding REQ_04_03_15
Normative generic format POST {accessingPartyBaseURI}/{resource}
Example POST {accessingPartyBaseURI}/position
Push vehicle position according to subscription.
REQ_04_03_16 A subscription shall have a status. The status can be:
—  ACTIVE (default),
—  INACTIVE (no resources will be pushed).
REQ_04_03_17 The accessing party should be able to deactivate an existing subscription in order
to pause the push of related resources.
REQ_04_03_18 The accessing party shall be able to reactivate an existing subscription in order to
resume the push of related resources.
REQ_04_03_19 A subscription can be deactivated by the offering party if the push request re-
turns errors.
REQ_04_03_20 If the offering party has set a subscription to INACTIVE,
—  reason,
—  HTTP status code, and
—  timestamp in the ISO 8601 series of last push attempt
shall be provided.
Table 27 contains a list of defined reasons.
NOTE 14 See Table 27 for possible reasons.
Table 27 — Reason for deactivation of subscriptions regarding REQ_04_03_20
TOKEN_EXPIRED Refresh token or bearer token provided in a subscription is expired.
AUTH_ERROR Push request returns authorization error.
AP_SERVICE_NOT_AVAILABLE Callback endpoint provided in a subscription is not reachable (after max
number of retries).
PUSH_HTTP_STATUS_CODE HTTP status code returned to push request.
RENEW_TOKEN_ERROR Cannot get a new access token.
TIMEOUT Push request takes too long to complete.
NOTE 15 The offering party can define additional reason values.
REQ_04_03_21 HTTP GET can be used by accessing party to request a list of subscriptions.
NOTE 16 See Table 28.
Table 28 — Examples of requesting a list of resource subscriptions regarding REQ_04_03_21
Normative generic format GET {baseURI}/subscriptions
Table 28 (continued)
Example of requesting a list GET {baseURI}/subscriptions
of resource subscriptions
Returns all available subscriptions for resources for an accessing party including
corresponding profileId.
Response payload:
{“subscriptions” : [
{“subscriptionId”=”1eb16206-0179-4ade-b5ea-08b6e6b4ebd5”,
“resource”=”positionSubscriptions”,
“profileId”=”2233”,
“status”=”ACTIVE”
},
{“subscriptionId”=”1eb16206-0179-4ade-b5ea-01b3e6b4ebd0”,
“resource”=” odometerSubscriptions”,
“profileId”=”2233”,
“status”=”INACTIVE”,
“reason”=”AUTH_ERROR”,
“httpStatusCode”=”402”,
“timestamp”=”2020-02-24T09:29:11Z”
}
]
}
Inactive subscription contains timestamp of last unsuccessful push request.
4.4 HTTP header fields
REQ_04_04_01 A client shall send a host header field in all HTTP/1.1 request messages, see
[6]
RFC 7230 .
NOTE 1 The server name is the same as the “Host” name as outlined in the extended vehicle URI format; see
Table 1.
REQ_04_04_02 The HTTP request header fields “Authorization” shall be present in every client
HTTP request.
REQ_04_04_03 The HTTP request header field “Accept” shall identify the media type the client
accepts in the response from the server.
REQ_04_04_04 The HTTP response header field “Content-Type” shall be present in every server
HTTP response with content.
REQ_04_04_05 The HTTP request header field “Authorization” shall use the “Bearer” authentica-
tion scheme to transmit a token.
NOTE 2 The generation, format and use of the token is further specified in ISO 20078-3.
4.5 Media types
REQ_04_05_01 The media type: application/json; utf-8 should be supported in HTTP request and
response messages.
REQ_04_05_02 Media types that may be supported in HTTP request and response messages are:
—  text/plain; utf-8,
—  text/xml; utf-8,
—  application/octet-stream (for raw binary data).
NOTE 1 Binary data can also be embedded in JSON or XML messages, typically using Base64 encoding.
REQ_04_05_03 At least one media type shall be selected when requesting data.
4.6 Resource versioning
REQ_04_06_01 The resource versioning shall be done on the resource level.
REQ_04_06_02 The API versioning may be done in the URL.
REQ_04_06_03 The resource version shall be identified by a custom parameter exve-resource-
version included in the request and response header fields “Accept” and “Con-
tent-Type”.
REQ_04_06_04 Syntax of the custom parameter exve-resourceversion shall be:
{media type}; exve-resourceversion={usecase resource.}v{major.minor}
NOTE 1 Resource representation with higher major version number is not compatible with lower major
version number. For example, resource version v2.0 is not compatible with v1.1.
NOTE 2 Minor version number indicates compatible changes in resource representation of same release. For
example, resource version v2.0 is compatible with v2.1.
REQ_04_06_05 As character encoding, utf-8 shall be used in accept-charset or content HTTP head-
ers.
NOTE 3 The use case resource with path is a unique path + name for the resource type.
NOTE 4 The resource version is the version of the resource that the client wants to be returned. It does not
have to be the latest available on the server, but the latest the client can handle.
NOTE 5 The requested return format is the format the client wants to have the response in (e.g. JSON, XML),
following REQ_04_05_02.
EXAMPLE Media types indicating resource versions, when versioning on resource level:
application/json; exve-resourceversion=resourcereadout.v1.0; charset=utf-8
application/xml; exve-resourceversion=resourcereadout.v1.0; charset=utf-8
REQ_04_06_06 Available versions for each resource shall be documented in the use case specific
resources.
REQ_04_06_07 If no version is defined in the accept header, the latest version shall be returned.
4.7 Resources and web services
Resources are exposed through web services. In most cases there is a many-to-many relationship
between resources and web services. This subclause outlines how web services and resources relate to
each other and how granting of resources is reflected when exposing them through web services.
4.7.1 General
REQ_04_07_01 A web service shall include one or more resources.
REQ_04_07_02 A resource may be included in many web services.
REQ_04_07_03 Granting access to a resource, either directly or through a container, shall give ac-
cess to that resource only in the web services exposing it.
NOTE 1 If all resources in a web service are granted, full access to the web service is given.
NOTE 2 If no resource in a web service is granted, no access to the web service is given.
NOTE 3 If a subset of the resources in a web service is granted, partial access to the web service is given; there
might be cases where no access can be given, due to how the web service is structured.
REQ_04_07_04 The web service specification shall not be changed in any way, due to granting, de-
nying, ignoring, or revoking access of included resources.
4.7.2 Examples
Table 29 shows examples of how resources are exposed in web services and how granting of these
resources affects what is accessible.
Table 29 — Resources exposed in web services
Resource:
Example Resource Web service Grant Access
web service
1 A A A A
1:1
2 B B — —
Table 29 (continued)
Resource:
Example Resource Web service Grant Access
web service
A A
3 AB AB
B B
C C
N:1 4 CD C (if possible)
D —
E —
5 EF —
F —
G’ G’
6 G G
G’’ G’’
1:N
H’ —
7 H —
H’’ —
Table 29
...