Open API generation from domain models
other
Linktoparent |
---|
Project Details
Page properties | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Relevant SDG targets:
Text Area | ||||
---|---|---|---|---|
| ||||
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
form-textarea-macrodefault | <click here to edit> |
---|---|
id | 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. [IMAGE] 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 :
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
- Open API 3.x specification : https://www.openapis.org/
- Australian
- government
- API
- design
- best
- practices
- :
Project Scope
Text Area | ||||
---|---|---|---|---|
| ||||
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
Text Area | ||||
---|---|---|---|---|
| ||||
Deliverable 1: Technical Specification Deliverable 2: Guidelines |
Exit Criteria
Text Area | ||||
---|---|---|---|---|
| ||||
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
Text Area | ||||
---|---|---|---|---|
| ||||
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
Text Area | ||||
---|---|---|---|---|
| ||||
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
Text Area | ||||
---|---|---|---|---|
| ||||
The geographical focus of the project is global. |
Beneficiaries
Text Area | ||||
---|---|---|---|---|
| ||||
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
Text Area | ||||
---|---|---|---|---|
| ||||
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
Attachments | ||
---|---|---|
|