API Town Plan
other Linktoparent
Project Details
| Page properties | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
| Excerpt |
|---|
Project purposeAs more and more UN/CEFACT business domains publish API standards, there is a risk of confusion and overlaps/gaps unless there is a well-managed architecture where every domain knows where they fit and all users can easily navigate the plan to find the APIs they need. This project will establish a high level “API town plan” and associated governance and publishing framework for all UN/CEFACT APIs. This project will be complete and proven successful when:
Project scopeThe green boxes on the right of the diagram represent a conceptual vision of the published town plan.
|
The town plan is a high-level artefact that is managed by a UN/CEFACT architecture function (to be created) and contains only
- A list of business domains, most likely well aligned with current forum structure. Each domain has a name, description, owner, and linked document repository.
- A list of API resources (ie interfaces) owned by the domain. For example, the /consignments resource would be owned by the transport domain. Each resource has a name, description, and specification URL.
- A list of dictionary entities and code lists managed by the domain.
The detailed API specifications and dictionary semantics are managed by the relevant business domain not by the central architecture function. However the architecture function may provide a quality review of candidate specifications prior to release from “draft” to “active” status.
- The “Trade” domain is expected to include resources such as TradeItems, invoices, orders, remittances, etc.
- The “Transport” domain is expected to include resources such as shipments, consignments, containers, movements, etc.
- The “Regulatory” domain is expected to include resources such as declarations, certificates, permits, etc.
- The “Finance” domain is expected to include resources such as (letters of) credits, insurances, loans, etc.
This project will deliver a first draft town plan and a governance framework for ongoing maintenance of the town plan as a living framework. The town plan will be maintained as a structured data set (eg a JSON file) and will be published as both structured data and a live clickable HTML page. The named resources (eg “/consignments”) on the town plan will be colour coded to indicate their status
- Grey would mean that the need for the resource has been agreed with the responsible domain – but the detailed API specification has not yet been published.
- Blue would mean that there is a detailed specification completed to at least draft quality level. Blue resources would be hyperlinked to the corresponding OpenAPI3.0 specification and JSON-LD dictionaries.
The project will also deliver at least one documented use case that highlights the use of the town plan and associated API specifications for a long running complex trade process such as a multi-modal transport scenario for an international consignment.
Project Deliverables
The project deliverables are:
- Deliverable 1
- Internal publication: First Draft Town Plan: A Domain / Resource map for all CEFACT domains and API resources. Agreed with each domain and published as a live web page.
- Deliverable 2
- Internal publication: Governance Model: Definition of a new role (CEFACT Architecture) and associated lightweight governance procedures to support ongoing maintenance of the town plan.
- Deliverable 3
- Internal publication: Detailed API specifications: At least two complete examples of API specifications from at least two different domains.
- Deliverable 4
- Internal publication: Use case: Multimodal international consignment use case documented and reviewed/approved by transport domain.
Exit Criteria
The exit criteria will be:
- For Deliverable 1
- First draft town plan agreed with domains and published internally.
- For Deliverable 2
- Governance procedures ready for internal publication.
- For Deliverable 3
- 4 x API specifications (2 resources in 2 domains) published at draft quality level for internal publication.
- For Deliverable 4
- Multimodal transport use case internally published.
Project Team Membership and Required Functional Expertise
Membership is open to UN/CEFACT experts with broad knowledge in the area of:
- International trade & transport procedures subject matter expertise
- Regulatory procedures subject matter expertise
- Information modeling
- RESTful API design
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.
Geographical Focus
The geographical focus is global.
Initial Contributions
The following contributions are submitted as part of this proposal. It is understood that these contributions are only for consideration by the Project Team and that other participants may submit additional contributions in order to ensure that as much information as possible is obtained from those with expertise and a material interest in the project. It is also understood that the Project Team may choose to adopt one or more of these contributions “as is”.
List any initial contributions:
- Depends on “alpha” quality RDM2API specifications & tooling
- Depends on existing published UN/CEFACT RDMs.
Resource Requirements
No additional secretariat resources will required.
Project Leadership
Proposed: Steven Capell
Project Proposal Files
| Attachments | ||
|---|---|---|
|