URI Conventions

This document is a publication of Het Normo. In the pursuit of completeness and correctness of data, we kindly request you to submit comments, additions and improvements regarding this document by raising a ticket in this repository.

Document annotations

Please find the following information here:

Changes - for all changes in this publication
Signoffs - for notification and signoffs for publication
References - for references to other publications
Dictionary - explanatory guide for terms and abbreviations

Table of contents

• Document annotations
• Table of contents
• Introduction
• Coherence of the concepts URI, URN, URL and resource
• General principles
  • ID 01
  • ID 02
  • ID 03
  • ID 04
• URI naming
  • Introduction to naming
  • Mandatory structure of URIs
  • Protocol component
  • Authority component
  • Path component
  • Result for <Path>
  • Query component
  • Fragment component
• Resulting structure of an energy sector URI
  • Energy sector URI naming convention
  • Examples of energy sector URIs

Introduction

This publication completes the Het Normo API design rules with a strategy on URIs and is the result of the effort of the API Strategy Working Group. In order to make REST APIs retrievable, it is necessary to give them a digital address. Within the context of the Internet, these addresses are called URIs, with the most common form being a URL, also known as a link. The URI guidelines were chosen to be inspired by the URI strategy of the DSO as this strategy is mature and well thought-out. In addition, the sector itself also provides information services to the government. Various parties in the sector must themselves connect to the web services of the Dutch government. The present URI strategy is thus based on the following sources¹:

• API strategy for the Dutch government;
• API strategy of the DSO;
• URI strategy of the DSO;
• Insights from Alliander, Enexis, Stedin and EDSN.

URIs can be used for several things. The government distinguishes the following four different categories:

1. Web pages of user applications;
2. SOAP web services;
3. REST APIs;
4. Linked Data.

Since this URI strategy focuses on API use, we limit ourselves (for now) to REST API URIs. However, the application of the convention discussed here already takes into account the use for other methods (see Method of unlocking (technique)).

Why is there a need for URI guidelines? URIs are inextricably linked to APIs. Every piece of information and/or functionality that is offered via an API needs an identification (URI), which makes a REST API discoverable and accessible. URI guidelines provide a practical translation for identifying APIs by developing a structure.

This document only describes the URI strategy and does not discuss its substantive application. For information on APIs, we refer to the Het Normo API design guidelines. The use of this naming convention is limited but leading to use within the CMF. In practice, this applies to all REST APIs that EDSN and other sector organisations build and maintain. Other market roles are advised to follow these guidelines as much as possible.

Coherence of the concepts URI, URN, URL and resource

To understand this topic properly, a bit of explanation is needed about the definition of URIs, URNs and URLs. URIs provide a mechanism to refer to resources regardless of where they are located on the Internet. URIs are human-readable because this simplifies interpretation and establishing relationships. A “resource” can be anything, such as physical objects (transformer, cable, geographic location), abstractions (concept, model) as well as information elements (web page). The abbreviations URNs, URIs and URLs all contain the term “Resource”. The resource is the basic concept on which the entire naming convention is based.

A Uniform Resource Identifier (URI) is a standardized way to identify sources of information(web pages, text, images, etc.) on the Internet. A URI identifies a resource by a hierarchical description (string of characters) that usually represents a location on a network. URIs are unique references to digital objects. Identification by a URI enables interaction with different sources of information over a network (such as the World Wide Web). The most common form of a URI is the Uniform Resource Locator (URL), often referred to as a web address. URL and URN are both specific forms of a URI. A Uniform Resource Name (URN) uniquely describes the name of a “resource”. A URN is a URI, but not a URL. This means that a URN without being embedded in a URI or URL cannot be found on the Internet. A Uniform Resource Locator (URL) uniquely describes the location of a “resource”, and this location can be found on the Internet. A URL is used to give others access to a resource. Within the DSO, URLs are used for SOAP services, REST APIs and Linked Data resources that are offered sector-wide.

flowchart LR
    uri([URI]) --> n1[\Name\] & n2[\Location\]
	n1 --> urn([URN])
	n2 --> url([URL])

Examples of URIs are:

• ftp://ftp.is.co.za/rfc/rfc1808.txt
• http://www.ietf.org/rfc/rfc2396.txt
• ldap://[2001:db8::7]/c=GB?objectClass?one
• mailto:John.Doe@example.com
• telnet://192.0.2.16:80/
• urn:oasis:names:specification:docbook:dtd:xml:4.1.2

General principles

REST APIs are popular because of their simplicity and reuse of the HTTP protocol. This protocol uses a subset of the generic URIs discussed above, namely URLs.

The following principles apply to all URIs:

ID 01

URIs are resource-oriented

ID 02

URIs are stable for a long time

ID 03

Central URIs are named independently of the organisation

ID 04

The URIs are written in lower case, except for the <Query> part.

URI naming

Introduction to naming

To arrive at a good naming of objects (in this context: resources) is not trivial. The reason is that a name only has meaning for people, not for systems. A name can therefore be called completely arbitrary. The names proposed here for URI objects are built up from various characteristics. For each characteristic, a consideration will be made as to whether it is meaningful in the context of the energy sector and what the best way to fill this in is.

Mandatory structure of URIs

The basic structure of the Het Normo API URIs follows the internet standard RFC3986:

<Protocol>://<Authority>/<Path>[?<Query>][#<Fragment>]

The generic structure above will be used as a starting point for specifying the REST URIs.

Protocol component

For the protocol standard (or “scheme” in the RFC) we apply the de facto standard.

<Protocol> will be https

The HTTPS protocol offers transport security and is a de facto standard.

Authority component

For <Authority>, we distinguish several characteristics as mentioned here.

Security aspects

You can choose to add security features to the URI with advantages and disadvantages.

Examples with security attribute:

• https://<Authority>/public/<other URI components>
• https://<Authority>/internal/<other URI components>

Example without security attribute:

• https://<Authority>/<other URI components>

We choose the first option here (1):

Do not include security attributes of APIs in the URI.

The motivation is that users can find out for themselves what their rights are when accessing the API. Adding a security attribute does not make the API itself secure, but there is a chance that this attribute will change over time. In practice, in both cases (both options 1 and 2), the APIs are secured by, for example, an API gateway that can assign rights per resource (outside the scope of the URI strategy).

Exposure method (technique)

Functionalities can be offered within a selected <Authority> (domain name) in various technical ways. Examples of these are REST APIs, SOAP web services, Linked data, etc. There are various options to indicate this distinction (in this case: ‘api’):

1. Include the method of exposure in the <Authority> section. Example: https://<designation>.api.<top domain>/<other Path characteristics>
2. Include the method of exposure in the <Path> section within the resource section. Example: https://<Authority>/<other Path characteristics>/api/<other Path characteristics>

The advantages and disadvantages of both options:

We choose option (1) here:

Add method of disclosing as subdomain in the <Authority> section.

Motivation: This choice makes it possible to support different protocols side by side for the same resources. Examples:

• api
• service

Note: although the scope of this document only concerns URIs with respect to the API design guidelines, the naming convention proposed here also provides for web services. However, this does not mean that agreeing to this convention means that all existing web services must have a different URI. For the time being, only the term “api” will be used in the domain section.

Environment designation

Following the DSO, we also use an environment designation. For this, we use the existing agreements within EDSN. It is proposed to fill this in as follows:

The designation “prd” can be used internally, but in accordance with good practice, we will leave this designation out for our external users (after all, no one surfs to https://www.prd.google.com).

Routing

In the government’s environmental law system the idea is that there is one national entrance for questions on environmental law and that these are routed to the correct municipality, province, etc. To make this possible, fixed URLs are used that forward the question to the relevant government institution at the back-end. This institution then takes care of further processing.

Within the energy sector, geographical location is much less decisive than with the environmental law. What is decisive is that certain central, national systems are now maintained by different organisations (e.g.: CPS at TenneT, CMF services at EDSN) and that without a routing function there is no possibility to address these services independently of the organisation.

The advantage of a routing function within the naming of the energy sector is that there will no longer be dependency on names of business units or executive bodies. If something changes here, only the end point of the routing needs to be adjusted, the service will still be retrievable by the customer using the same URI.

There are two methods to include the routing function in the URI:

1. include it in the <Authority> section (the domain section)
2. include it in the <Path> section (the resource section)

The advantages and disadvantages of both options:

We choose option (1) here:

Included in the <Authority> section.

Motivation: Subdomain routing is a simple way to route traffic while using one fixed (main) domain name.

Sub domain

There are several options on which to base the choice for a subdomain:

1. On business function
2. On organisation
3. On existing hubs or portals
4. On future hubs or portals
5. On registry

The advantages and disadvantages of the different options:

We choose option (3) here:

Subdomain routing based on existing hubs or portals.

Motivation: This option is good long-term stability, with low impact and costs. Option 1 is even more long-term stability, but this means, among other things, drawing up an exhaustive list of business functions and applying them to URIs and existing web services.

Overview of central hubs and portals:

Top domain

When choosing the main domain name of the <Authority>, the following options were considered:

1. The domain name of the API provider; e.g. in the case of Het Normo: “hetnormo.nl”
2. An organization-specific national domain name for all APIs such as “edsn.nl” or “netbeheernederland.nl”
3. A new generic domain name to be chosen nationally such as “netbeheer.nl” or “nutssector.nl”
4. International persistent domain names such as “purl.org” or “w3id.org”

The following table shows the substantiation for the choice between the different alternatives:

We choose option (3) here:

Applying a national generic domain name: energysector.nl (domain is reserved by EDSN).

motivation: With this choice, the URI is the most persistent and resilient to organizational changes. Since (much) functionality is offered nationwide, coordination can be sought per project/initiative on the exact functionality and method of offering. For information: the domain “energiesector.nl” was already registered by Eneco.

Authority result

The above selections result in the following convention:

https://api.<environment>.<routing>.energysector.nl

Examples for <Authority>:

• api.acc.cmf.energysector.nl
• api.wse.energysector.nl (not: api.prd.wse.energysector.nl)

Path component

Resources can be classified flatly or hierarchically. However, the hierarchical classification provides direct insight into the context in which the resource is placed. We therefore opt for a hierarchical classification with multiple levels.

Root level

There are several options for filling in the root level:

1. based on the business unit that manages the resources
2. based on the department that manages the resources
3. based on the team that unlocks the resources
4. based on the business function (such as Operations, Asset Maintenance, etc.) in which the resources are used
5. based on business objects on level 1 of the NBility BOM model
6. based on so-called ‘Bounded Contexts’
7. based on Value Streams or ARTs from EDSN

We choose the fifth option here (5):

Use an NBility business object (level 1) for the root level of the <Resource>.

Motivation: Business objects are the most stable and provide context to the APIs to be developed and the terms used. In addition, this prepares one best for the future when any new business objects arise during the energy transition. With the arrival of NBility in September 2021, the joint grid operators use the same names for their business objects. By agreement, we always use the English translations of these business objects for the application in URIs. Because business objects have a strong relationship with business functions and processes that affect these business objects, they are described in NBility as so-called capabilities. A capability is derived from business objectives and represents everything needed to achieve the set business results. Simply put: in the context of URI naming, a capability includes the CRUD (Create, Read, Update and Delete) operations on a business object.

Sublevels

As the root level follows the NBility business object model (BOM for short), the second and third level of the <Path> conform to the BOM on the levels of NBility. In an addendum the current levels are listed.

API name (last part)

This level represents all related resources and the associated business function. The name should be as generic as possible to allow for later expansion of the API without having to name a new API. As a guideline, a contraction of the NBility object at level three and the capability at level three can be used.

Note that NBility 2.3 mentions different capabilities

The contractions in the last column are not an official part of the NBility model.

To facilitate future naming and to implement naming as uniformly as possible, here is a list of keywords that are leading for the API name:

In some cases, other API names can also be used if the standard classification according to NBility is not sufficient. This is the case, for example, if:

• Level 3 is still too coarse. For example: the further subdivision of Power Generating Modules into Type A and Type BCD
• If the API unlocks multiple resources that are classified under different objects in NBility. For example: the EAN codebook API contains both the grid operator name (object 6.1.1 market-participant) and the EAN18 of the connection (object 6.2.1 connection)

Version within <Path>

The URI attribute <version> specifies the version number of the API. This attribute consists of the letter “v” followed by a number. This number is the major version number of the API. The version number starts at 1 and is incremented by 1 for each major release where the interface changes (and backward compatibility is not guaranteed). Minor version numbers are in the message itself. Adding a non-mandatory attribute to the payload is an example of a change that is backward compatible.

Collection within <Path>

The subdivision into collections is necessary to distinguish the different resources that belong to one API from each other. This is the lowest level of resources. Following others, such as Google, this is called a collection. The URI component <Collection> identifies the collection resources from which data is returned. A collection is comparable to classes in object orientation and the objects are the actual resources.

There are several options for determining the names of collections or resources:

1. Definitions from Dutch/European legislation
2. Definitions from the CIM
3. Definitions from NBility
4. Determined by a delegation of network operators and EDSN

Because resources occur in many different contexts and their meaning depends on the context in which they are used, no choice is made here for one of the options, but a preference for application in the given order. When naming resources, Dutch legislation therefore prevails over the definitions from the CIM standard, which in turn prevail over the business objects from NBility. The last option is to choose a resource name yourself (by a delegation of network operators and EDSN) if the models/standards do not (cannot) provide for this. This name will then have to be explained to the users. The name of a resource will have to be determined by a delegation of network operators and EDSN. Currently (early 2023), this task lies with the API Strategy Working Group, which, in addition to the name, also checks the specification of APIs for the CMF domain, for the correct application of the API and URI guidelines.

Result for <Path>

The choices made in this section result in the following structure of the component <Path>:

/<root level>/<sublevel 1>/<sublevel 2>/<API name>/<version>/<collection>

For the filling of the resources of a collection, it is best to use existing standards or models. This filling will always be stated in the plural form.

Query component

The URI component <Query> optionally specifies additional parameters that act as a filter on the result of the API call.

Possible applications of queries are:

• Filtering/Searching: when the user of the API is interested in a part of the dataset, this can be achieved by means of a query. This is comparable to a where statement in an SQL query. From the DSO we adopt the restriction to specify a maximum of five (5) query parameters per call. If more than five are needed, a POST must be used.
• Pagination/Sorting: See agreements on this in Het Normo API design guidelines.

Fragment component

The URI component <Fragment> optionally specifies a reference to the identification of a resource within the collection in accordance with the principle: reuse the identification mechanisms where possible as described in the reference models.

Resulting structure of an energy sector URI

Energy sector URI naming convention

Combining all components mentioned in the previous chapter results in the following naming convention:

https://api.<Environment>.<Routing>.energysector.nl/<Root level>/<sublevel 1>/<sublevel 2>/<API name>/<Version>/<Collection>/{ID}[?<Query>][#<Fragment>]

Examples of energy sector URIs

As a first example, we will mention an API that can be used to manage contracts for market services. These are contracts for balancing capacity, redispatch capacity or demand management.

A URI based on the above example would then be as follows formed:

https://api.cmf.energysector.nl/energy-market/market-participant/market-agreement/contractmanagement/v1/market-agreements/879999999999999999

Some actual examples:

Some compositions deviate from the standard derivation in section 3.5.4