JSONTouchDevelop cloud service API

TouchDevelop cloud execution API

JSON

JavaScript Object Notation – Based on a subset of JavaScript

Programming Language - Standard ECMA-262 3rd Edition - December 1999

.

WHY JSON ?

• “Lightweight data-interchange format.• Easy for humans to read and write.• Easy for machines to parse and generate.• Has a text format is completely independent

of any programming language.• Has conventions that is familiar to

programmers of basic languages (c, c++, java, Perl, Phyton, etc.)”[1]

Its Structure

• JSON is built on two structures:• “A collection of name/value pairs. In various

languages, this is realized as an object, record, struct, dictionary, hash table, keyed list, or associative array.”[1]

• “An ordered list of values. In most languages, this is realized as an array, vector, list, or sequence.”[1]

An Object

“Object an unordered set of name/value pairs.

An object begins with { (left brace) and ends with } (right brace). Each name is followed by : (colon) and the name/value pairs are separated by , (comma).”[1]

• Examples of objects:myObject1 = {};

myObject2 = { "first": “Harry", "last": “Potter", "age": 17, "sex": "M“ };

myObject2.age returns 17myObject2[“age"] returns 17

myObject3 = { "first": “Harry", "last": “Potter", "age": 17, "sex": "M“, “favorites” : { “sports”: “Quiddich” ,

“class”: “Defense against the Dark arts”, “professor”: “Dumbledore” } };

myObject3. favorites.sports returns Quiddich myObject3[“favorites "][“sports"] returns Quiddich

An Array

“Array is an ordered collection of values.

An array begins with [ (left bracket) and ends with ] (right bracket). Values are separated by , (comma).”[1]

Example of JSON Arrays

• myArray1 = [];• myArray2 = [ [], {} ];• myArray3 = [ “Harry Potter", 17, true, null ]

myArray3[2] returns true

• myArray4 = [ { "name": “Harry", "age": 17 }, { "name": “Ron", "age": 17}, { "name": “Gini", "age": 16} ]

myArray4[0].name returns Harry

Value

“A value can be a string in double quotes, or a number, or true or false or null, or an object or an array..”[1]

String

“A string is a sequence of zero or more Unicode characters, wrapped in double quotes, using backslash escapes.A character is represented as a single character string. A string is very much like a C or Java string.”[1]

Number

TouchDevelop cloud service API

• All TouchDevelop scripts are stored and analyzed in the cloud.

• TouchDevelop exposes a set of web services to query scripts, users, comments, screenshots, reviews, leaderboard scores, and tags.

Conventions used..

• HTTP: Hyper Text Transfer Protocol

• REST : Representational State Transfer– All APIs are REST based.

• JSON– APIs return either structured JSON objects or plain

text

URLs

• All APIs are exposed via URLs of the form http://www.touchdevelop.com/api/....

• The results of all requests under the /api/ prefix return results which are not meant for direct human consumption.

count, continuation

• While querying lists results are returned in batches.

• &count=[count] parameter can be added with value between 10 to 1000.

• &applyupdates=true to return latest updates.• Non-empty continuation token in JASON

response -> add query parameter &continuation=[continuation].

Publication ids

• Each script, user, comment, screenshot, review, tag has a unique id, in general referred to as its publication id. Example of userid “id":"ahdg“Example of scriptid "id":"byxb“Example of commentid “id":"lqmhwzoh"

• Publication ids are sequences of lower-case latin letters, at least four letters long. The ids are randomly assigned by TouchDevelop.

APIsThe following queries return lists that enumerate all available objects.

• /api/scripts queries all scripts;• optional parameters: ?count=[number]&continuation=[token]&etagsmode=[etagsmode]&q=[text]

• /api/users queries the list of users; • optional parameters:

?count=[number]&continuation=[token]&etagsmode=[etagsmode]&q=[text]

• /api/comments queries the list of comments;• optional parameters:

?count=[number]&continuation=[token]&etagsmode=[etagsmode]&q=[text]

• /api/screenshots queries the list of screenshots;• optional parameters:

?count=[number]&continuation=[token]&etagsmode=[etagsmode]

APIs condt…• /api/reviews queries the list of reviews; • optional parameters:

?count=[number]&continuation=[token]&etagsmode=[etagsmode]

• /api/tags queries the list of all tags; • optional parameters:

?count=[number]&continuation=[token]&etagsmode=[etagsmode]&q=[text]

• /api/art queries the list of all art; • optional parameters:

?count=[number]&continuation=[token]&etagsmode=[etagsmode]&q=[text]

• /api/documents queries the list of all documents; optional parameters: ?count=[number]&continuation=[token]&etagsmode=[etagsmode]&q=[text]

APIs condt…The following queries return lists that enumerate a particular subset of all available objects.• /api/search?q=[text] performs a full-text search over users, scripts, comments, tags,

features; pass the search text as a URL-encoded query parameter; • optional parameters:

&count=[number]&continuation=[token]&etagsmode=[etagsmode]

• /api/new-scripts queries scripts ordered by time;• optional parameters:

?count=[number]&continuation=[token]&etagsmode=[etagsmode]

• /api/top-scripts queries scripts ordered by popularity; • optional parameters:

?count=[number]&continuation=[token]&etagsmode=[etagsmode]

• /api/featured-scripts queries list of featured scripts; • optional parameters:

?count=[number]&continuation=[token]&etagsmode=[etagsmode]

Example URIs• /api/scripts?count=20• /api/scripts?count=20&continuation=S2520837450019190298-oylo• /api/search?q=missile• /api/users?count=100• /api/users?q=samples• /api/comments?count=1000• /api/comments?q=awesome• /api/screenshots?count=1000• /api/reviews?count=1000• /api/tags?count=1000• /api/tags?count=1000&q=games

JSON format

• Each JSON-formatted response contains a kind field that states the type of the response; depending on the kind, other fields are available.

• The following kinds and other fields may be returned

list

• kind: "list"• items: array of items• continuation: continuation token (if non-

empty string)

List example..

• {"kind":"list","items":[{"kind":"tag","time":1335530617,"id":"games","url":"http://www.touchdevelop.com/games","name":"games","category":"","description":"Any kind of games.","instances":308,"topscreenshotids":["lrqqerul","zvvyyfqh","lstx","mmrr","ansm"]},{"kind":"tag","time":1335565368,"id":"action","url":"http://www.touchdevelop.com/action","name":"action","category":"games","description":"Action games titles including side-scrollers, first-person shooters, fighting, and others.","instances":84,"topscreenshotids":["uasumlvm","aygja","stdn","auvfspbj","pqbv"]},{"kind":"tag","time":1335565548,"id":"board","url":"http://www.touchdevelop.com/board","name":"board","category":"games","description":"Chess, Roulette, and all other board and casino games.","instances":67,"topscreenshotids":["lgrzrzcj","ofmvdhlw","dynj","fzwokzbc","lyss"]} ],"continuation":null}

script• kind: "script"• time: time when script was created• id: script id• url: script website for human consumption• name: script name• description: script description• userid: user id of user who published script• username: user name• userscore: user score• userhaspicture: whether the user has a picture• icon: script icon name• iconbackground: script icon background color• iconurl: script icon picture url• positivereviews: number of users who added to this script♥

• subscribers: number of users subscribed to this script• comments: number of discussion threads• screenshots: number of screenshots• capabilities: array of capabilities used by this script; each capability has two fields: name, iconurl• haserrors: whether this script has any compilation errors• rootid: refers to the earliest script along the chain of script bases• updateid: refers to the latest published successor (along any path) of that script with the same name and from the same user• ishidden: whether the user has indicated that this script should be hidden• islibrary: whether the user has indicated that this script is a reusable library• installations: an approximation of how many TouchDevelop users have currently installed this script• runs: an estimate of how often users have run this script• librarydependencyids: a list of script ids that are referenced as libraries• art: number of art used by this script• toptagids: ids of top tag given by most users

Script example..

{"kind":"script","time":1359035344,"id":"mhmi","url":"http://www.touchdevelop.com/mhmi","name":"Ohm\u0027s law","description":"A classic Ohm\u0027s Law converter.","userid":"pboj","username":"TouchDevelop Samples","userscore":1265,"userhaspicture":true,"icon":"AlmostEqual","iconbackground":"#FFA500","iconurl":"http://cdn.touchdevelop.com/c04/frdz.png","positivereviews":1,"subscribers":0,"comments":0,"screenshots":0,"capabilities":[],"platforms":["webonly"],"flows":[],"haserrors":false,"rootid":"xtcbb","updateid":"pnwf","ishidden":false,"islibrary":false,"installations":0,"runs":0,"librarydependencyids":[],"art":0,"toptagids":[],"screenshotthumburl":null,"screenshoturl":null}

user• kind: "user"• id: user id• url: user website for human consumption• name: user name• about: user's about-me text• features: number of features used by that user• receivedpositivereviews: number of given to this user's scripts ♥

and comments• subscribers: number of users subscribed to this user• score: overall score of this user• haspicture: whether this user has a picture

User example..

• {"kind":"user","id":"pboj","url":"http://www.touchdevelop.com/pboj","name":"TouchDevelop Samples","haspicture":true,"about":"Sample scripts written by the TouchDevelop team","features":667,"receivedpositivereviews":556,"subscribers":129,"score":1265}

comment

• kind: "comment"• time: time when comment was created• id: comment id• url: comment website for human consumption• text: comment text• userid: user id of user who published comment• username: user name• userscore: user score• userhaspicture: whether the user has a picture• publicationid: script id that is being commented on, or parent comment id if nestinglevel>0• publicationname: script name• publicationkind: "script"• nestinglevel: 0 or 1• positivereviews: number of users who added to this comment♥

• subscribers: number of users subscribed to this comment• comments: number of nested replies available for this comment

{"kind":"comment","time":1353615800,"id":"rjykstvu","url":"http://www.touchdevelop.com/rjykstvu","text":"Awesome :)","userid":"pboj","username":"TouchDevelop Samples","userscore":1265,"userhaspicture":true,"publicationid":"bgxdjdlb","publicationname":"Draw3D","publicationkind":"script","nestinglevel":1,"positivereviews":0,"subscribers":0,"comments":0}

reviews

• kind: "review"• time: time when review was created• id: review id• userid: user id of user who published review• username: user name• userscore: user score• userhaspicture: whether the user has a picture• publicationid: script id that is being reviewed• publicationname: script name• publicationkind: "script" or "comment"• ispositive: "true" indicates a ♥

tag

• kind: "tag"• time: time when tag was created• id: tag id• url: tag website for human consumption• name: tag name• category: tag category (if any)• description: tag description• instances: how often the tag was applied

Other JSON objects…

• screenshot• art• leaderboardscore• document

Using ETags in list queries

• &etagsmode=[etagsmode] for list queries can be used to reduce the data transfers required to perform queries and responses.

“The etagsmodecan be one of the following.

• includeetags: The list response will not only contain a items field, but also an ids field, containing an array of objects of the form { "id": $id, "ETag": $hash }, indicating the ETag value that a separate /api/$id request would have returned for each $id.

• etagsonly: The list response will contain an ids field, and items will be omitted.”[2]

Examples:• /api/scripts?etagsmode=includeetags• /api/scripts?etagsmode=etagsonly

ETag/If-None-Match headers

• “Every successful response contains an ETag header representing a stable hash derived from the content of the response.

• This hash can be passed in as part of a future

request via a If-None-Match header. If the content matches the given hash, a 304 Not modified response status code is returned and the unchanged response content is omitted.”[2]

Publications properties.With publication id, we can query certain properties.We can get the script text, or its compiled abstract syntax tree by querying /api/[scriptid]/text and/api/[scriptid]/ast.

• /api/[id] info about a script, user, comment, screenshot, review, tag or art

• /api/[scriptid]/text raw text of a script; optional parameters: ?original=[boolean]

• /api/[scriptid]/ast compiled abstract syntax tree of a script

• /api/[scriptid]/successors list of all successor scripts of a script; • optional parameters:

?count=[number]&continuation=[token]&etagsmode=[etagsmode]

• /api/[scriptid]/base base script of a script

Publication properties API..

• /api/[scriptid or userid or tagid]/screenshots list of all screenshots for a script or from a user or associated with a tag; optional parameters:

• ?count=[number]&continuation=[token]&etagsmode=[etagsmode]

• /api/[commentid or scriptid or userid]/reviews list of all reviews for a comment or script or from a user; optional parameters: ?count=[number]&continuation=[token]&etagsmode=[etagsmode]

• /api/[scriptid or userid]/leaderboardscores list of all leaderboard scores for a script or from a user; optional parameters: ?count=[number]&continuation=[token]&etagsmode=[etagsmode]&recent=true

• /api/[scriptid or userid or commentid or tagid]/subscribers list of all subscribers of a script or user or comment or tag; optional parameters: ?count=[number]&continuation=[token]&etagsmode=[etagsmode]

Examples:• /api/ecvs for the info about script with id /ecvs; status code 404 if no such script id• /api/ecvs/text for the raw text of the script with id /ecvs; status code 404 if no such script

id• /api/ecvs/ast for the compiled abstract syntax tree of /ecvs; status code 404 if no such

script id

• /api/fhxu/base for the base script of /fhxu; status code 404 if no base exists

• /api/pboj/scripts for a list of all scripts by the user /pboj• /api/pboj/comments for a list of all comments by the user /pboj• /api/pboj/screenshots for a list of all screenshots by the user /pboj• /api/pboj/reviews for a list of all reviews by the user /pboj• /api/pboj/leaderboardscores for a list of all leaderboard scores by the user /pboj

batch requests

• “Bundling involves encoding HTTP requests and responses in JSON form.

• POST request to /api, with a JSON body containing a batch of requests.

• A batch request may include at most 50 individual requests.”[2]

Batch request example..

• HTTP Request:• GET http://touchdevelop.com/api/$path If-None-Match: $hash

• Encoded JSON as:

• { "method": "GET", "relative_url": "$path", "If-None-Match": "$hash" }

Batch request example..

• Bundling an array of requests• [ $request1, $request2, ..., $requestN ]

• JSON-encoded form, as follows.• { "array": [ $request1, $request2, ..., $requestN ], "If-None-Match": "$hash" }

• Responses come in array form as well.• { "code": 200, "array": [ $response1, $response2, ..., $responseN ],

"ETag": "$hash" }

TouchDevelop cloud execution API

“Cloud execution enables us to access scripts remotely and run them in the cloud.”[3]

Conventions..

experimental research features.under heavy development.No access restrictions.

• http, rest, jsonAll APIs are exposed as REST services; the APIs

return structured JSON objects.

API

• Format:• /api/[scriptid]/run/[actionname]?$

[argname1]=[argvalue1]&$[argname2]=[argvalue2]&…

’$’ must be included Named action must not be a private or must

not be an event.

Examples..

• /api/clhb/run/fibonacci?$x=3 call the action “fibonacci” from the script

Fibonacci algorithm /clhb passing “3” as argument for “x”

• /api/irdk/run/get%20rates?$from=JPY&$to=RUB call the action “get rates” from the script

Currency exchange /irdk Passing “JPY” and “RUB” as arguments for “from” and

“to” respectively.

• “Arguments when not supplied takes corresponding default values.

• Parameter kinds supported are:BooleanNumberStringDateTime• If any other kind, the execution engine assigns

the corresponding default values.”[3]

Response format

• If successful:{ "success": true, "result": [result1, result2, …] }

• If unsuccessful:{ "success": false, "error": errorMsg }

Example..

Action request to the cloud:• /api/irdk/run/get%20rates?$from=JPY&$to=RUB

Successful response returned:• { success: true, result: [true, 0.4066356021376903] }

Example..

Action request to the cloud:• /api/irdk/run/get%20rate?$from=JPY&$to=RUB yields

Failed response with error message:• { success: false, error: "Cannot find action get rate in script

irdk" }

global state

• “Scripts that use global state are also supported via cloud execution.

• The current model assigns a separate global state on a per-script/per-user basis and stores it in the cloud. It is persisted between separate calls to the cloud execution API.

• Execution is done starting from a default global state, and the final state is not persisted at the end of execution if the user is not logged in.

• Concurrent access to the same script by the same user is managed using “last-update-wins” policy.”[3]

limitations

• “Not all TouchDevelop APIs are supported.

• If a script invokes an unsupported API, then script execution will continue using the result value invalid.

• The list of encountered unsupported APIs is returned as part of the JSON response in a field called unsupported.

• Maximum execution time is limited and depends on system load.”[3]

References

[1] http://www.json.org/

[2] https://www.touchdevelop.com/help/cloudservices

[3] https://www.touchdevelop.com/help/cloudexecution