Introduction

These Standards & Guidelines provide comprehensive documentation on how we, at Deutsche Post DHL, design, implement and maintain APIs.

For suggestions or changes, please contact us via the help center.

Goals

  • Providing functionality to third parties, via standardized technical interfaces (APIs) in order to consume our products and services digitally.

  • Having a harmonized approach to provide APIs to third parties and internal units of Deutsche Post DHL.

  • Apply best practices by leveraging comparable approaches seen in the industry.

The purpose of Deutsche Post DHL API Standards & Guidelines is to:

  • Ensure that Deutsche Post DHL’s APIs functional and non-functional characteristics are harmonized and follow a defined set of standards and recommendations.

  • Ensure that Deutsche Post DHL’s APIs are designed, developed and tested, deployed, published, operated, consumed, analyzed, updated and retired along with a lifecycle based on commonly used best practices.

Target Audience

The primary target audience for this Standards & Guidelines are Product Owners, IT architects and API developers at Deutsche Post DHL. Additionally, this document is publicly available for the general audience to understand how we do APIs.

What is covered by these API Standards & Guidelines

These API Standards & Guidelines cover the high-level, conceptual governance along the API lifecycle, API design constraints, patterns, tools, and processes overview. It is not the intention of these guidelines to govern the internal technical procedures (e.g., how to implement or where to deploy a service). Their respective internal documents should guide these.

APIs in Scope

The API Standards & Guidelines focuses on APIs developed and maintained by Deutsche Post DHL, including all its business divisions, which are published on the API Developer Portal (https://developer.dhl.com/). All APIs published on this Developer Portal MUST follow the Group's API Standards & Guidelines.

Other published APIs and internal APIs SHOULD (that means it is recommended, especially for new APIs) also follow the Group’s API Standards & Guidelines.

Hereafter, the term "API" simply refers to the "Web API" and "GraphQL API" unless stated otherwise.

APIs in Scope

API Architectural Styles

The API Standards & Guidelines focuses on REST architecture as the widely adopted architecture for APIs at Deutsche Post DHL. The API Standards & Guidelines also acknowledges GraphQL as a potential API architectural style to be used.

Further modern styles, such as Real-time APIs will be added to the guidelines if and when they become relevant to Deutsche Post DHL. The API guidelines do not have legacy styles such as SOAP, file-based integration or EDI integrations in scope.

Reading the Standards & Guidelines

The API Standards & Guidelines provide recommendations that are expressed using the RFC 2119 keywords. To avoid misinterpretation especially among non-native speakers, the word MUST is to be used rather than SHALL.

RFC2119

The key words "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT,"
"SHOULD," "SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in 
this document are to be interpreted as described in RFC2119.

Living Document

These guidelines will be extended and updated continuously based on ongoing discussion and experience.

To support the discussion, the API Standards & Guidelines include the explanation of the reasons for individual decisions.

These explanations are outlined as quotation blocks.