Education - General prerequisites

From Alistair Mann / csi18n
Jump to: navigation, search

API

csi18n provides an API, an Application Programming Interface.

Like all APIs, csi18n is not the final product itself like Apple Pages, or Angry Birds, but provides facilities that final products can use.

Using csi18n means you can bring crowd-sourced translation facilities into your own product, without the expense of professional translators, without the timelag on foreign market research, and without the need for language pack installs, or even complete foreign language builds of your product.

cURL for Windows

This is optional unless you use Microsoft Windows.

cURL is a command-line program used to send and receive messages to and from servers on the Internet. Specifically, it's used here to reveal the behaviour of HTTP.

If you use Windows, you can obtain a copy here. Look down towards the bottom of the page: most Windows users will want the Win64-Generic binary SSL version, and to copy the file downloaded into c:\windows. If you use 32bit Windows, or prefer to use Cygwin etc, you'll need to root about for the appropriate download.

If cURL complains about MSVCR100.dll being missing, you'll also need to install the Microsoft Visual C++ 2010 SP1 Redistributable Package.

An additional wrinkle for Windows users is that single and double-quotes need to be handled differently. In Windows, double quotes need to be escaped, so " becomes \"; single quotes need to become unescaped double quotes, so ' becomes "
Normally:
curl -i -X POST -H 'Connection: close' -H 'X-APIKey: 798e31c43d6b9f03aa504a6f88cb4550' -H 'Content-Type: application/json;v=1.0' -u 'test05:test' --data '{"csi18n_xlate_resource":{"language":"en-CA","translation":"Congraturation - A winrar is you","visibility":"personal"}}' https://rest.mpsvr.com:443/newmarks/1/A-winner-is-you

Windows:
curl -i -X POST -H "Connection: close" -H "X-APIKey: 798e31c43d6b9f03aa504a6f88cb4550" -H "Content-Type: application/json;v=1.0" -u "test05:test" --data "{\"csi18n_xlate_resource\":{\"language\":\"en-CA\",\"translation\":\"Congraturation - A winrar is you\",\"visibility\":\"personal\"}}" https://rest.mpsvr.com:443/newmarks/1/A-winner-is-you

The former method is used on this site, so if you use an example here on a Windows machine and it seems to go wrong, check whether the quotes style is correct.

HTTP methods

The Hypertext Transfer Protocol is not designed merely for retrieving web pages and associated media, but is a fully bi-directional means of handling both download and upload of resources. In this, HTTP has more in common with protocols like FTP and SMB than it does with one-way protocols like POP3. This service aims to comply with RFC2616, replaced in June 2014 by RFCs7230-7237. Compliance with these later RFCs will be looked into later.

There are six HTTP methods used by the csi18n service. Each method involves a header and a body.

  • GET & HEAD. To GET a resource is to download that resource from the server to the client. To HEAD it is to do a GET, but only receive the headers -- useful to save bandwidth.
  • DELETE. To DELETE a resource is to so arrange things that subsequent access to that resource behaves identical to that resource having never existed in the first place.
  • OPTIONS. To OPTIONS a resource is to ask context of the server: what may be done with this resource? This commonly obtains what methods the client could use with this resource, and in some places I've extended this to obtaining English-language documentation about use of the resource.
  • PUT. If you know the location the resource is to appear at, then PUT creates the uploaded resource at that location.
  • POST. If you don't know that location, and want the server to create it, then POSTing that resource creates it and retrieves the location it was created at.

PUT vs POST

Assume records are numeric, and live at locations #1, then #2, then #3 etc. You cannot tell ahead of time what location your next record will appear at: it could be #4, but then it could at #5 should someone else upload a record to #4 first. POST is appropriate here: the server will decide the next location, use it, and tell you about it.

Having POSTed a record, you now know that it lives at location #3, and that goes into your service. But weeks later you discover an error in that record. Rather than rewrite to use a new location altogether, you can upload an edit to location #3. PUT is appropriate here. The server supercedes what's at #3, with what you upload.

The above is a huge simplification: httpbis is worth a read for more insight.

REST

There are two manners of providing a service over the web: Arbitrary, and Representational State Transfer - csi18n uses the latter.

REST is a standards-friendly mechanism to provide disparate developers stable access to a service. As csi18n aspires to be compliant with HTTP, developers should not need to learn any protocol other than HTTP in order to effectively use it. By contrast, an Arbitrary service (such as the eBay API) requires more effort. For example, consider this eBay API example: Deleting requires the creation method POST(!), as opposed to the deletion method DELETE, and requires a response to be parsed for success, not merely examination of the response code.

The csi18n service aims to comply with the mandatory architectural constraints of RESTful services:

  • Client/Server separation. For example, the client worries about the user interface, the server worries about storing data. In an arbitrary service, the two can get mixed up.
  • Stateless: For example, there's no sense of logging in, logging out - the credentials required are passed at every exchange.
  • Cacheable & Layered: (Although not tried yet,) The exchanges to and from the csi18n server can be cached by proxies
  • A uniform interface: For example, resources can all be passed backwards and forwards as an XML representation. Or JSON, or HTML, and so on, all using the same HTTP methods.

RESTful-ness also means Hypermedia as the engine of application state is given effect.

While the REST concepts are new to most, I believe resulting APIs are accessible to a wider range of developers and reduces development time vs Arbitrary services.