other
Project Details
|
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. |
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
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
Relevant links
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. |
Deliverable 1: Technical Specification Deliverable 2: Guidelines |
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. |
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. |
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 |
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. |
This project builds upon work already completed by UNECE and partner organisations.
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 |