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:
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!
Our Application Programming Interface is entirely made of Web Services. Nothing else! It permits two types of interaction:
OpenLabels has decided to split the services between REST API compliant services and Non-Standard services.
REST API compliant services have been designed to permit long-term references.
The endpoint of the OpenLabels REST API
compliant services is
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
OpenLabels responds to Web Services in 3 possible ways/formats:
The default response mode is 'HTML'. It is ideal for quick results and debugging.
The only charset that is used is
In all the below examples the values of the
parameters are presented in angle brackets:
If a parameter is optional, the entire parameter block is
presented in square brackets (e.g.
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:
Here's the same service that will send its result in JSON:
Remember that the output format is all driven by these
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.
keyparameter. A list of labels can be requested in one call: the
keyparameter must then be a tokenized list of labels (^ separated).
languageparameter is not part of the query, all values are returned, disregarding the language as a filter (but maybe other filters will narrow the results).
taxonomyparameter is not part of the query, all values are returned disregarding the taxonomy as a filter (but maybe other filters will narrow the results).
satoriparameter is part of the query, the result is ALWAYS rendered in XML by default. The
satoriparameter 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
keyare all returned. The output format can still be set to JSON if the
jsonparameter is mentioned in the query.
download: the download service permits to download the OpenLabels databases as XML file(s). If the
dateparameter is sent, it must be provided in the
YYYYis the year in 4 digits,
MMis the month in 2 digits and
DDis the day in 2 digits. Month and day are both optional in the format, which is also optional in whole. When the
dateparameter is provided the closest database match is returned. If the
dateparameter is not sent, the most recent version of the database is returned.
downloadservice always sends the OpenLabels databases in a zip archive, which contains the XML files.
The SET services are NOT defined yet at this time (23/06/2013 13:28:15).
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 services' preferred output format is XML. All services do respond in a standard manner.
<OpenLabelsService> <Service name="..."> <Request><![CDATA[...]]></Request> <Response>...</Response> </Service> </OpenLabelsService>