An OSI-like API

StackLately, APIs have been largely discussed in translation-related events, blogs, and media. Some pundits have gone so far as to extend the so-called API economy to the translation industry.

The concept of API economy dates back to the beginning of this century, with the positive explosion of the World Wide Web, sanctioned by the so-called Web 2.0.

An API is a set of subroutine definitions, protocols, and tools for building application software. In general terms, it is a set of clearly defined methods of communication between various software components. APIs make software development easier by providing all the building blocks, which are then put together by the developer.

The popularization of APIs with their extension to web-based systems has been helping the growth of web-based services and ultimately the associated economy.

With the usual delay, even the translation industry, for a couple of years, has discovered APIs and the role they can play in automating its old-fashioned and often sluggish tasks and processes.

Obviously, so far, only the major players, who have the necessary skills or the resources to acquire them, have shown a real interest, although implementations have often been scarce, inadequate, and disappointing.

And this despite the translation industry has always been affected by a lack of interoperability.

So far, most of the efforts in defining standards for translation have focused on processes and file formats rather than addressing (system) interactions.

Indeed, writing an API specification is a complex technical task and, as the saying goes, there is no such thing as a free lunch. So, it is understandable that anyone with the necessary skills, capacity, and resources might not be willing to make an API specification freely available and possibly do a favor to its competitors.

In the same way, it is understandable that any initiative in this respect, especially if initiated by bodies associating the largest players, is received with skepticism if not mistrust.

The risk of failure is even higher when yielding to the audacity of describing a universal API in its objects, methods, and calls, possibly providing not just some code snippets, but a fully-fledged implementation.

A set of recommendations to manufacturers of translation tools and platforms for developing their own APIs to perform the basic tasks in a translation assignment would possibly be welcome and followed, and in any case better received than an allegedly universal API that might be perceived as an over-extending imposition.

On the contrary, the definition of an open and flexible web-service API model addressing the most common use cases might help either its adoption by a plateau of potential users, or its acceptance, as such, by a standardization body thus leaving everyone at liberty while providing a reference framework for future certification.

In other words, describing how a translation management API should work might be the most straightforward way to have the industry comply and for a certification body to validate compliance.

This blog post is meant to present the idea of the possible application of the OSI model for a translation management API.

Being the model open, any implementation should just follow a few basic design principles addressing the most common use cases in translation and localization management. Ideally, to be certified as compliant, any API should also be open.

Any compliant API should then be capable of:

  • Being implemented across all systems;
  • Being consumed from any point similarly;
  • Conveying bids and quotes;
  • Submitting raw or prepared material;
  • Getting translated material back.

The model

Conceptually, the model shows the communication flow between two systems without regard to the underlying internal structure and technology. Its goal is the interoperability of the systems with standard architectures and protocols.

The model partitions the communication flow into consecutive abstraction layers with different functionalities. A layer serves the layer above it and is served by the layer below it, from top to bottom.

The model embryo depicted here comes from the idea of a stateful multi-layer process, with every stage of job having a “status”.

A basic implementation of this model should be an API providing a minimal set of simple interactions to cover the most common tasks, from inquiry to request to project launch.

To be compliant, an implementation won’t have to go through all layers: It could consist only of some, provided they respect the original consecutive sequence.

The layers

Layer 1 deals with the typical interactions of a general inquiry. The prospecting customer submits a request for information to the candidate vendor containing general information about a possible translation project. The status may be “opened.” The vendor reply (accepted/rejected) would trigger a change in status: “awaiting/closed.”

Layer 2 deals with quotation. The candidate vendor submits a request for information to the prospecting customer to issue a quotation. The customer reply (accepted/rejected) would trigger a change in status: “in progress/closed.” This layer also deals with the exchange of any useful data (including content samples) for quotation.

Layer 3 deals with negotiation. The parties negotiate the terms of the job. The status remains “in progress” unless the negotiation is terminated. In this case the status changes to “canceled.”

Layer 4 deals with project triggering. The customer sends the project payload to the vendor and the job status changes to “running.” The vendor acknowledged receipt and creates a task. An additional field is populated with the project status.

Layer 5 deals with project execution. The job status remains “running,” while the project status changes into “pending/assigned/in progress/paused/canceled/finished.” Pending means that the project has been created, and it is waiting to be assigned; assigned means that the project has been assigned to someone and it is about to start; in progress means that the project is being executed; paused means that the project has been temporarily stopped; canceled means that the project has been aborted, i.e. prematurely terminated or canceled; finished means that the project has been completed and delivered to customer.

As a project might consists of distinct tasks, each task is supposed to receive a status label. Only when all tasks are labeled as “finished/completed,” the project can be labeled as finished too.

Metadata

Metadata is crucial for the proper and complete execution of interactions. In a layered model, metadata must be used to label the data flowing from one layer to the other describing the project and the payload. Therefore, a common definition is necessary. Cases, classes and methods should be consistent in naming and notation with metadata definitions.

Also, the exchange of metadata must be limited to the minimum necessary to perform the interactions envisaged for a layer.

Interactions

What follows is a non-exhaustive list of possible interactions. Metadata is updated at every interaction.

  1. Request
    the customer requests the translation with any relevant parameters;
  2. Acceptance/rejection
    the customer or the vendor accepts/rejects the job
  3. Job creation
    the customer initializes the job;
  4. Project info
    the customer sends project metadata and samples for quotation to the vendor.
  5. Set AQL
    The customer sets the desired quality level for the translation from a list of available parameters.
  6. Negotiation
    the vendor sends the quotation to the customer
  7. Project initialization
    the vendor starts executing the project;
  8. Payload exchange
    customer and vendor(s) exchange payload;
  9. Project updates
    customer and vendor(s) exchange info;
  10. Project reports
    the customer requires, and the vendor sends out a status report;
  11. Project conclusion
    the vendor submits the translation to the customer;
  12. Project closure
    the customer cancels/aborts/terminates/finishes the project.