API Town Plan

other

Project Details

Project purpose

As 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:

• A first draft API town plan is published: As a clickable map covering Trade, Transport, Regulatory, and Financial domains as well as agriculture, tourism and other domains.
• A town plan governance framework is established: That defines how the town plan is managed and how new APIs are added.
• Conformant API Implementations are published: At least two domains have each followed the RDM2API methodology and have published at least one API that aligns with the town plan.

Project scope

The green boxes on the right of the diagram represent a conceptual vision of the published town plan.

• 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