| Text Area |
|---|
| default | <click here to edit> |
|---|
| id | project_purpose |
|---|
|
Not applicable – this underlying capability (methodology) that will be leveraged by all UN/CEFACT business projects that require API specifications. Consequently, all SDGs that are relevant for CEFACT projects are also relevant for this specification. |
Project Purpose
Web APIs based on Open API 3.0 (or later) standards are becoming an increasingly important technology for system-to-system data exchange interfaces. For UN/CEFACT to provide outputs that are relevant for modern web developers, it is critical that there is a consistent way to deliver API specifications for UN/CEFACT domain projects. The API generation can be incorporated into existing UN/CEFACT standard delivery methodology with minimal disruption. API specifications generated should be implementable and testable.
High quality APIs conform to the “RESTful” architecture where http verbs represent “actions” on business “resources”. Good APIs also include events where authorized users can subscribe to be notified when the state of a resource like a consignment changes state.
The diagram below shows the components of a REST API, using the consignment resource and transport & logistics domain as an example. Although the consignment resource is used as an example, the methodology and specification developed through this project will be equally applicable to all UN/CEFACT work areas. The key ideas are
- That an API resource is a digital representation of a real-world object and is always a noun.
- That resources are designed to be small and self-contained by having references to other resources, which are operated on by their own APIs.
- That a resource is represented by a logical data model and, of equal importance, a state lifecycle.
- That external systems use http verbs to interact with the resource through well defined actions (eg POST /consignments/{data} will create a new consignment and return it’s unique {id}, and GET /consignments/{id} will return information about a specific consignment.)
- That every transition in the state lifecycle of the resource (eg the “booked”, “in-transit”, “held”, “cleared” examples in the diagram) will trigger an event that will be sent to any subscribed and authorized external system.
- That resources are grouped into logical business domains so that they can be governed as a logical group based on a common domain vocabulary.
Well-designed APIs are easy to understand and easy to use because they map to clear and well understood real world business objects.
Domain Resource model for RESTful API design.
A UN/CEFACT Open API Naming & Design Rules technical specification already exists (see initial contributions). However, whilst it provides a good set of design principles to guide API developers, it does not provide a pathway from UN/CEFACT logical domain models (eg the RDMs) to Open API specification generation. One challenge with Open API generation is that there are many features of an open API specification that have no logical equivalent in logical domain models – so there’s nothing to map to. However, it should be feasible to embed a set of good API design opinions into a set of generation rules that are implemented as a separate template. In this way, a logical domain model with only a few simple annotations could be the source for a template-driven API specification generation.
Therefore, the purpose of this project is to empower UN/CEFACT business domain experts to use simple high level modelling tools to develop business domain models that are based on UN/CEFACT semantics – and then to generate rich Open API specifications with little effort. To achieve this outcome the project will define
- An API design methodology that is targeted at business domain experts. The methodology will leverage existing business domain knowledge encapsulated in existing UN/CEFACT reference data models and document standards.
- An extension to the exiting Open API technical specification that it targeted at tool vendors.
Relevant links
