Project 1

From Alistair Mann / csi18n
Jump to: navigation, search

On this page I'll take you through the process of using the service in your first project.

Decide your first newmark

A newmark is an identifier for a thing which needs translation, and we can use it even before deciding on what's to be translated.

For example, we can use "Great-Product-Name" as the newmark, as we're not yet sure counsel will let us name our new beverage "Kokah Kolah". By doing this we can get on with creating the product rather than getting hung up on the name, if we later have to change the name we won't have to rewrite all the links; it also considerably shortens links to use a newmark like "Book1-ch01-para03" rather than the entire text of whatever paragraph 3 might be.

A newmark can contain any characters known to unicode, but should be URL-encoded if necessary. "Hello World" is not allowed: use "Hello%20World".

You now know enough to create your first Visit link:
/newmarks/{subscriberid}/{newmark}
If your SubscriberID was #197, and the newmark you've chosen "A-winner-is-you", then your first Visit link will be
/newmarks/197/A-winner-is-you

With the server information too, your Visit link will be
https://rest.mpsvr.com:443/newmarks/197/A-winner-is-you
There's no need to do anything on the server to create that link. It's enough that your website/app/product knows that when it needs that text, it can find it from visiting that link.

Someone else with the same newmark cannot interfere with yours because of the SubscriberID in the link. Example: Pepsi-Koala have URI /newmarks/197/Best-Koala and Generic-Koala has /newmarks/198/Best-Koala. What's happens to one link is isolated from what happens to the other because of the differing SubscriberIDs. Further, Generic-Koala can't change Pepsi-Koala's website (app, etc) to refer to Generic-Koala's link instead for the same reasons they can't change anything else about Pepsi-Koala's website or products - they won't have the access rights.

Generic-Koala could re-use Pepsi-Koala's link on their own site, however, just as Generic could frameset Pepsi-Koala's website into their own. This facility is useful in instances like translating "Game Over" where an industry body could make a visit link available to all.

Retrieve your first translation

While you've created the above link, the server won't have received any translations for it yet. Let's prove that.

The following is a cURL command issued from a Bash shell on a Linux machine. cURL is available for a wide range of operating systems including Windows and OSX.

When trying examples out, remember to change the APIKey, username, password and SubscriberID to your own! (Also Windows users change the quote style)

In example below, the command line to be written out is highlighted first, and the response (which always starts "HTTP/1.1 ...") follows.

curl -i -X GET -H 'Accept-Language: en-CA' -H 'Accept: application/json' -H 'Connection: close' -H 'X-APIKey: 798e31c43d6b9f03aa504a6f88cb4550' -u 'test05:test' https://rest.mpsvr.com:443/newmarks/197/A-winner-is-youHTTP/1.1 404 Not found. Could be up Jack's or round Fanny's
Date: Sat, 27 Sep 2014 08:59:44 GMT
Server: Apache
X-Testing-Dupe: HTTP/1.1 404 Not found. Could be up Jack's or round Fanny's
X-CDMI-Date: 2014-09-27T09:59:44.273988Z
X-Server: mpsvr/2014Sep26-234458
Content-Length: 48
X-CDMI-Last-Modified: 2014-09-27T09:59:44.273988Z
Last-Modified: Sat, 27 Sep 2014 09:59:44 BST
Content-MD5: 86de39b2638bbbb9931ddeb00d2bb260
Connection: close
Content-Type: text/html
 
Not found. Could be up Jack's or round Fanny's

Sure enough, we get a 404 error - no translations were found because none have been uploaded.

Upload your first translation

Let's decide that the best Canadian English translation for what we want to express with "A-winner-is-you" is the text "Congraturation - A winrar is you".

We're going to jump ahead a bit and I'm going to tell you the data structure we'll use. Formatted as JSON, it looks like this:

{
 "csi18n_xlate_resource":
 {
  "language":"en-CA",
  "translation":"Congraturation - A winrar is you",
  "visibility":"personal"
 }
}
  • "csi18n_xlate_resource" is the name of the data structure containing the relevant facts
  • The language says that the following translation should be returned if a suitable request wanting Canadian English is received
  • The translation to be returned
  • Finally the visibility indicates who can see this translation.

Visibility can be "personal", "private", "public" or "anonymous": Summary below, More info here

  • personal translations may only be retrieved by the uploader
  • private translations are available to the superordinate and among the subordinate accounts he creates
  • public translations may be retrieved by any user on the server who has a valid account
  • anonymous translations may be retrieved by any user even if they have no account

To upload this translation, we use HTTP POST. Again, remember to change to your own credentials:

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-youHTTP/1.1 201 Created, good and proper
Date: Fri, 29 Aug 2014 15:31:48 GMT
Server: Apache
X-Testing-Dupe: HTTP/1.1 201 Created, good and proper
X-CDMI-Date: 2014-08-29T16:31:48.638094Z
X-Server: mpsvr/2014Aug29-031840
Location: https://rest.mpsvr.com/xlates/1/A-winner-is-you/en-CA/personal/336
ETag: "9074d83989659eb9546aae0f15c931f0"
Content-Length: 26
X-CDMI-Last-Modified: 2014-08-29T16:31:48.613166Z
Last-Modified: Fri, 29 Aug 2014 16:31:48 BST
Connection: close
Content-Type: text/html
 
Created, good and proper

This time, HTTP required we add a "Content-Type" header noting that the data is a JSON structure (version 1.0 here lets my service know which version of csi18n_xlate_resource this is. For the moment, there is only version 1.0)

The upload succeeded, and the server informed us of that with a 201 Created response along with the location of the created translation.

Retrieve first uploaded translation

We can repeat the earlier attempt to fetch:

$ curl -i -X GET -H 'Accept-Language: en-CA' -H 'Accept: application/json' -H 'Connection: close' -H 'X-APIKey: 798e31c43d6b9f03aa504a6f88cb4550' -u 'test05:test' https://rest.mpsvr.com:443/newmarks/197/A-winner-is-youHTTP/1.1 200 Ok. Done. Sorted.
Date: Sat, 27 Sep 2014 09:02:24 GMT
Server: Apache
X-Testing-Dupe: HTTP/1.1 200 Ok. Done. Sorted.
X-CDMI-Date: 2014-09-27T10:02:24.145228Z
X-Server: mpsvr/2014Sep26-234458
ETag: "8380d56f034b0eda426a9f30398ba448"
Content-Location: /xlates/1/A-winner-is-you/en-CA/personal/747
Content-Length: 698
X-CDMI-Last-Modified: 2014-09-27T10:02:11.293925Z
Last-Modified: Sat, 27 Sep 2014 10:02:11 BST
Expires: Sat, 27 Sep 2014 09:56:25 BST
Cache-Control: public
Content-MD5: 2fb7794887caedaa809dfd017b773c12
Connection: close
Content-Type: application/json
 
{"csi18n_xlate_resource":{"language":"en-CA","translation":"Congraturation - A winrar is you","visibility":"personal","datetime_last_change":"2014-09-27T10:02:11.293925Z","crid":747,"sid":1,"source":"only personal upload by user"},"csi18n_xlate_location":"\/xlates\/1\/A-winner-is-you\/en-CA\/personal\/747","previous_uploads":"\/xlates\/1\/search?crid=747&page=-1&visibility=personal","later_uploads":"\/xlates\/1\/search?crid=747&page=0&visibility=personal","previous_uploads_by_ip":"\/xlates\/1\/search?crid=747&ipv4=192.168.1.64&page=-1&visibility=personal","later_uploads_by_ip":"\/xlates\/1\/search?crid=747&ipv4=192.168.1.64&page=0&visibility=personal","search_form":"\/xlates\/1\/search"}

Your first upload, now sent back, looks like:

{
  "csi18n_xlate_resource": {
    "language": "en-CA",
    "translation": "Congraturation - A winrar is you",
    "visibility": "personal",
    "datetime_last_change": "2014-09-27T10:02:11.293925Z",
    "crid": 747,
    "sid": 1,
    "source": "only personal upload by user"
  },
  "csi18n_xlate_location": "\/xlates\/1\/A-winner-is-you\/en-CA\/personal\/747",
  "previous_uploads": "\/xlates\/1\/search?crid=747&page=-1&visibility=personal",
  "later_uploads": "\/xlates\/1\/search?crid=747&page=0&visibility=personal",
  "previous_uploads_by_ip": "\/xlates\/1\/search?crid=747&ipv4=192.168.1.64&page=-1&visibility=personal",
  "later_uploads_by_ip": "\/xlates\/1\/search?crid=747&ipv4=192.168.1.64&page=0&visibility=personal",
  "search_form": "\/xlates\/1\/search"
}

Notice the extra data:

  • datetime_last_change: The CDMI date and time of the upload, this will match X-CDMI-Last-Modified in the HTTP header. All persisted objects are stored using microseconds.
  • crid: The Continuity Record ID uniquely identifies the most recently uploaded copy of your translation. Previous versions, perhaps with spelling errors, have the same crid but are ignored for being older.
  • sid: This translation was originally uploaded against Visit Link /newmark/1
  • source: English language indication of how this translation was decided on. "only personal upload by user" here means that we have ourselves (upload by user) uploaded a single translation (only), and we gave it a visibility of personal. If chosen from among many others, we might see "semirandom public upload among other users"
  • csi18n_xlate_location: the location of the particular translation being returned. We asked https://rest.mpsvr.com:443/newmarks/1/A-winner-is-you for the best available Canadian English translation, and it tells us here the best available can be found directly at /xlates/1/A-winner-is-you/en-CA/personal/747
  • previous_uploads/later_uploads: Visiting these links would show us a page of translations that we uploaded immediately prior or subsequent to the translation we see here.
  • previous_uploads_by_ip/later_uploads_by_ip: The same as above, but the search is also confined to those translations uploaded from the same IP address
  • search_form: a shortcut to a page giving more in the way of search options

Edit your first translation

As we know the location of the translation is /xlates/1/A-winner-is-you/en-CA/personal/747, we use the HTTP method PUT.

Let's decide that there's no point using the dash between "Congraturation" and "A winrar", and we want to replace it. Our RESTful implementation means that we should be able to edit the change directly into the data structure, and PUT it right back where it came from. What will happen is that only language, translation and visibility will be looked at, and the rest of the data is ignored. So

        "translation":"Congraturation - A winrar is you",

... becomes ...

        "translation":"Congraturation  A winrar is you",

And the cURL exchange:

curl -i -X PUT -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","datetime_last_change":"2014-09-27T10:02:11.293925Z","crid":747,"sid":1,"source":"only personal upload by user"},"csi18n_xlate_location":"\/xlates\/1\/A-winner-is-you\/en-CA\/personal\/747","previous_uploads":"\/xlates\/1\/search?crid=747&page=-1&visibility=personal","later_uploads":"\/xlates\/1\/search?crid=747&page=0&visibility=personal","previous_uploads_by_ip":"\/xlates\/1\/search?crid=747&ipv4=192.168.1.64&page=-1&visibility=personal","later_uploads_by_ip":"\/xlates\/1\/search?crid=747&ipv4=192.168.1.64&page=0&visibility=personal","search_form":"\/xlates\/1\/search"}'  https://rest.mpsvr.com:443/xlates/1/A-winner-is-you/en-CA/personal/747HTTP/1.1 201 Created, good and proper
Date: Sat, 27 Sep 2014 09:10:54 GMT
Server: Apache
X-Testing-Dupe: HTTP/1.1 201 Created, good and proper
X-CDMI-Date: 2014-09-27T10:10:54.652833Z
X-Server: mpsvr/2014Sep26-234458
Location: https://rest.mpsvr.com/xlates/1/A-winner-is-you/en-CA/personal/747
Allow: GET, HEAD, OPTIONS, PUT
ETag: "4630053ba7dc6658fb91bf19cc61febc"
Content-Length: 26
X-CDMI-Last-Modified: 2014-09-27T10:10:54.622245Z
Last-Modified: Sat, 27 Sep 2014 10:10:54 BST
Content-MD5: 31d2c7f367c90ce0c8a1f4264fc372ca
Connection: close
Content-Type: text/html
 
Created, good and proper

Repeat the fetch from above, and what we'll get back is a 200-OK and the corrected response.

curl -i -X GET -H 'Accept-Language: en-CA' -H 'Accept: application/json' -H 'Connection: close' -H 'X-APIKey: 798e31c43d6b9f03aa504a6f88cb4550' -u 'test05:test' https://rest.mpsvr.com:443/newmarks/197/A-winner-is-youHTTP/1.1 200 Ok. Done. Sorted.
Date: Sat, 27 Sep 2014 09:12:04 GMT
Server: Apache
X-Testing-Dupe: HTTP/1.1 200 Ok. Done. Sorted.
X-CDMI-Date: 2014-09-27T10:12:04.708422Z
X-Server: mpsvr/2014Sep26-234458
ETag: "c058347b1f1fa8697e5304a2c47521ac"
Content-Location: /xlates/1/A-winner-is-you/en-CA/personal/747
Content-Length: 697
X-CDMI-Last-Modified: 2014-09-27T10:10:54.622245Z
Last-Modified: Sat, 27 Sep 2014 10:10:54 BST
Expires: Sat, 27 Sep 2014 10:06:11 BST
Cache-Control: public
Content-MD5: 94faa68adb8b8d5a879c602fa2fdf11a
Connection: close
Content-Type: application/json
 
{"csi18n_xlate_resource":{"language":"en-CA","translation":"Congraturation  A winrar is you","visibility":"personal","datetime_last_change":"2014-09-27T10:10:54.622245Z","crid":747,"sid":1,"source":"only personal upload by user"},"csi18n_xlate_location":"\/xlates\/1\/A-winner-is-you\/en-CA\/personal\/747","previous_uploads":"\/xlates\/1\/search?crid=747&page=-1&visibility=personal","later_uploads":"\/xlates\/1\/search?crid=747&page=0&visibility=personal","previous_uploads_by_ip":"\/xlates\/1\/search?crid=747&ipv4=192.168.1.64&page=-1&visibility=personal","later_uploads_by_ip":"\/xlates\/1\/search?crid=747&ipv4=192.168.1.64&page=0&visibility=personal","search_form":"\/xlates\/1\/search"}

Let me repeat: to edit a resource, you can download it, edit it "in-place", and send the resource back to the address it came from - there's no need to extract or decode or otherwise manipulate the data before you make changes.

You may upload edits as many times as you wish.

Delete your first translation

The HTTP method DELETE, sent against the appropriate URI, deletes the translation: success gets a 204-No Content response.

In cURL:

curl -i -X DELETE -H 'Connection: close' -H 'X-APIKey: 798e31c43d6b9f03aa504a6f88cb4550' -u 'test05:test' https://rest.mpsvr.com:443/xlates/1/A-winner-is-you/en-CA/personal/747HTTP/1.1 204 No content of our the winter this is
Date: Sat, 27 Sep 2014 09:14:20 GMT
Server: Apache
X-Testing-Dupe: HTTP/1.1 204 No content of our the winter this is
X-CDMI-Date: 2014-09-27T10:14:21.083455Z
X-Server: mpsvr/2014Sep26-234458
ETag: "d41d8cd98f00b204e9800998ecf8427e"
Content-Length: 0
X-CDMI-Last-Modified: 2014-09-27T10:14:21.083455Z
Last-Modified: Sat, 27 Sep 2014 10:14:21 BST
Connection: close
Content-Type: text/html

Notice that while repeating the fetch above will now correctly obtain a 404-Not Found response, the data itself remains on the server and can be obtained in other ways.


At this point, you should be able to recognise the intent of cURL commands.