OpenLabels API

Good To Know

We're still debating! What you read here is a living draft! We're still discussing how all things can be best specified and implemented. Here are some of our fundamentals:

  1. Retrieve a collection of labels
    • Individual labels (label by label) (and a collection of labels can be just ONE single label)
    • Labels that participate to a discourse (context)
  2. … from whatever programming language where the http protocol can be used and more particularly from PHP and JavaScript
  3. Get a response in HTML, XML or JSON
  4. All this must be accessible from a browser (no access to the request headers such as Accept-Language, Accept, method, …)

Therefore we are basing our web services on REST … without being tourmented by REST purity! What counts is that Developers find the labels they need. Period!

Getting Started

Our Application Programming Interface is entirely made of Web Services. Nothing else! It permits two types of interaction:

  1. GET interaction (CRUD): with the GET interactions you can retrieve information from OpenLabels databases. A special GET interaction is the possibility to download the full set of databases freely.
  2. SET interaction (CRUD): with the SET interactions you can set information into OpenLabels databases: create, update and delete.

OpenLabels Web Services

OpenLabels has decided to split the services between REST API compliant services and Non-Standard services.

REST Services

REST API compliant services have been designed to permit long-term references.

The endpoint of the OpenLabels REST API compliant services is http://api.openlabels.net/labels

Non-Standard Services

When services cannot be served in a REST API compliant way in a satisfactory manner, we kindly ask Developers to turn to our Non-Standard Web Services. We call them Non-Standard because they do not necessarily follow the purity of the REST rules (OpenLabels is driven by code efficiency: less code and faster results).

The endpoint of the OpenLabels Non-Standard web services is http://api.openlabels.net/queries

Response Formats (for REST API compliant services AND Non-Standard Web services)

OpenLabels responds to Web Services in 3 possible ways/formats:

  1. HTML
  2. XML
  3. JSON

The default response mode is 'HTML'. It is ideal for quick results and debugging.

Charset (for REST API compliant services AND Non-Standard Web services)

The only charset that is used is utf-8.

Conventions

In all the below examples the values of the parameters are presented in angle brackets: lbl=<term>. If a parameter is optional, the entire parameter block is presented in square brackets (e.g. [&lng=<language>]).

All web services accept the following output format parameters: XML or JSON. Please remember that all results are sent in HTML by default. For example, the label service can be called in the following manner to indicate that the desired output should be sent in XML:

http://api.openlabels.net/labels/label/?key=$firstname&lng=en&xml

Here's the same service that will send its result in JSON:

http://api.openlabels.net/labels/label/?key=$firstname&lng=en&json

Remember that the output format is all driven by these parameters, xml and json. That's it! In particular the OpenLabels web services completely neglect the Content-Type header sent in the HTTP request. As a consequence, the following attempts are completely disregarded:

Content-Type: text/xml, application/xml, application/xhtml+xml

OpenLabels, when it creates the output, uses the HTTP headers to pass additional information to the caller. When the output is formatted as XML or JSON, the complementary information is also sent in the payload of the response.

GET Services

  1. label: the label service returns the value of a given label (or set of labels) in a given language (optional) for a given taxonomy (optional).
    The label to look for is passed in the key parameter. A list of labels can be requested in one call: the key parameter must then be a tokenized list of labels (^ separated).
    If the language parameter is not part of the query, all values are returned, disregarding the language as a filter (but maybe other filters will narrow the results).
    If the taxonomy parameter is not part of the query, all values are returned disregarding the taxonomy as a filter (but maybe other filters will narrow the results).
    If the satori parameter is part of the query, the result is ALWAYS rendered in XML by default. The satori parameter indicates a true and lasting realization of the nature of the label to look for. In other terms, the inner details of the label identified by key are all returned. The output format can still be set to JSON if the json parameter is mentioned in the query.
    The label web service can be shortened as lbl.

    Syntax:

    http://api.openlabels.net/labels/label/?key=<term>[&lng=<language>][&taxo=<taxonomy>][&satori]
    

    HTML Example:

    http://api.openlabels.net/labels/label/?key=$firstname&lng=en
    

    XML Example:

    http://api.openlabels.net/labels/label/?key=$firstname&lng=en&xml
    
    http://api.openlabels.net/labels/label/?key=$firstname^$lastname&lng=en&xml
    

    JSON Example:

    http://api.openlabels.net/labels/label/?key=$firstname&lng=en&json
    
  2. download: the download service permits to download the OpenLabels databases as XML file(s). If the date parameter is sent, it must be provided in the YYYY[MM[DD]] format where YYYY is the year in 4 digits, MM is the month in 2 digits and DD is the day in 2 digits. Month and day are both optional in the format, which is also optional in whole. When the date parameter is provided the closest database match is returned. If the date parameter is not sent, the most recent version of the database is returned.
    The download service always sends the OpenLabels databases in a zip archive, which contains the XML files.
    The download service can be abbreviated as dwld.

    Syntax:

    http://api.openlabels.net/labels/download/[?date=<YYYY[MM[DD]]>]
    

    Example DRAFT:

    http://api.openlabels.net/labels/download/
    

SET Services

The SET services are NOT defined yet at this time (23/06/2013 13:28:15).

OpenLabels Database

We're just starting: don't be too harsh on us! If you feel you can help, please join the "OpenLabels" community on Google+ or send us an email so that we add you to our list of contributors.

Here's the structure of the current test database labels.xml (utf-8 encoded):

<Dictionary active="yes|no">
    <Data key="..." active="yes|no" editable="yes|no" checked="YYYYMMDD" approved="YYYYMMDD" taxonomy="..." id="..." alias="...">
        <Value lang=".."><![CDATA[Some value]]></Value>
    </Data>
    …
</Dictionary>

OpenLabels Web Wervices Responses (draft)

OpenLabels services' preferred output format is XML. All services do respond in a standard manner.

<OpenLabelsService>
    <Service name="...">
        <Request><![CDATA[...]]></Request>
        <Response>...</Response>
    </Service>
</OpenLabelsService>