Open API generation from domain models

other

Project Details

P1128

#2401006, #2411018

BR, SE, SI, KR

1.0

2023-12-14

2025-02-28

2025-03-30

Relevant SDG targets:

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

1. 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.
2. An extension to the exiting Open API technical specification that it targeted at tool vendors.

Relevant links

• Open API 3.x specification : https://www.openapis.org/
• Australian government API design best practices : https://api.gov.au/sections/wog-api-requirements.html 

Project Scope

This project will 
•	Define an API design methodology for business domain experts which minimises the need for technical expertise. The methodology will allow them to extend their business domain models to support API specification generation – using any tool that conforms to the specification. 
•	Define a specification for generation of API specifications from domain models. This specification is targeted at tool developers.  The API specifications will conform to the OpenAPI 3.x standard.
•	Support implementation of the specification in at least one modelling tool that is accessible by UN/CEFACT business domain experts.

Project Deliverables

Deliverable 1: Technical Specification
Deliverable 2: Guidelines

Exit Criteria

The exit criteria will be:
Deliverable 1: Public Review logs demonstrating all comments have been satisfactorily resolved; Final document ready for publication.
Deliverable 2: Final document ready for publication.

Impact analysis

UN/CEFACT electronic standards for trade facilitation, sustainability, and e-business will become less relevant in the modern world unless they can also be provided as API specifications. Therefore, this project delivers wide-scale applicability across-the-board value to uplift the relevance and uptake of such UN/CEFACT standards.

Project Team Membership and Required Functional Expertise

In addition, Heads of Delegations may invite technical experts from their constituency to participate in the work.
Experts are expected to contribute to the work based solely on their expertise and to comply with the UN/CEFACT Code of Conduct and Ethics and the policy on Intellectual Property Rights.
https://unece.org/trade/documents/2010/12/session-documents/intellectual-property-rights-policy 

Geographical Focus

The geographical focus of the project is global.

Beneficiaries

Most SME’s use commercial small-business software for managing their business.  Modern API specifications from UN/CEFACT could facilitate implementation of data interchange capabilities that bring them to a common level with larger enterprises, thereby levelling the playing field for SMEs.

Initial Contributions

This project builds upon work already completed by UNECE and partner organisations.

• UN/CEFACT BSP RDM and its domain specific subset RDMs upon which the JSON-LD vocabulary is based. These will be used as examples for the design methodology guidance paper delivered by this project.
• UN/CEFACT OpenAPI Naming and Design Rules V1.0UN/CEFACT. This is the technical specification that will be extended by this project.
• JSON-LD vocabulary : vocabulary.uncefact.org. The generated API specifications should also align with the UN/CEFACT JSON-LD vocabulary so that instance messages can include a “@context” reference that allows for automated interpretation of semantic meaning.

Resource Requirements

Participants in the project shall provide resources for their own participation. The existence and functioning of the project shall not require any additional resources from the UNECE secretariat

Project Proposal Files