Presentation is loading. Please wait.

Presentation is loading. Please wait.

JSON TouchDevelop cloud service API JSON TouchDevelop cloud service API TouchDevelop cloud execution API TouchDevelop cloud execution API.

Similar presentations


Presentation on theme: "JSON TouchDevelop cloud service API JSON TouchDevelop cloud service API TouchDevelop cloud execution API TouchDevelop cloud execution API."— Presentation transcript:

1 JSON TouchDevelop cloud service API JSON TouchDevelop cloud service API TouchDevelop cloud execution API TouchDevelop cloud execution API

2 JSON JavaScript Object Notation – Based on a subset of JavaScript Programming Language - Standard ECMA-262 3rd Edition - December 1999.Standard ECMA-262 3rd Edition - December 1999

3 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]

4 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]

5 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]

6 Examples of objects: myObject1 = {}; myObject2 = { "first": “Harry", "last": “Potter", "age": 17, "sex": "M“ }; myObject2.age returns 17 myObject2[“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

7 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]

8 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

9 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]

10 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]

11 Number

12 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.

13 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

14 URLs All APIs are exposed via URLs of the form The results of all requests under the /api/ prefix return results which are not meant for direct human consumption.

15 count, continuation While querying lists results are returned in batches. &count=[count] parameter can be added with value between 10 to &applyupdates=true to return latest updates. Non-empty continuation token in JASON response -> add query parameter &continuation=[continuation].

16 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.

17 APIs The 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]

18 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]

19 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]

20 Example URIs /api/scripts?count=20 /api/scripts?count=20&continuation=S oylo /api/scripts?count=20&continuation=S 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

21 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

22 list kind: "list" items: array of items continuation: continuation token (if non- empty string)

23 List example.. {"kind":"list","items":[{"kind":"tag","time": ,"id":"games ","url":"http://www.touchdevelop.com/games","name":"games","c ategory":"","description":"Any kind of games.","instances":308,"topscreenshotids":["lrqqerul","zvvyyfqh", "lstx","mmrr","ansm"]},{"kind":"tag","time": ,"id":"actio n","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","st dn","auvfspbj","pqbv"]},{"kind":"tag","time": ,"id":"boa rd","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}

24 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

25 Script example.. {"kind":"script","time": ,"id":"mhmi","url":"ht tp://www.touchdevelop.com/mhmi","name":"Ohm\u00 27s law","description":"A classic Ohm\u0027s Law converter.","userid":"pboj","username":"TouchDevelop Samples","userscore":1265,"userhaspicture":true,"icon": "AlmostEqual","iconbackground":"#FFA500","iconurl":"ht tp://cdn.touchdevelop.com/c04/frdz.png","positiverevie ws":1,"subscribers":0,"comments":0,"screenshots":0,"ca pabilities":[],"platforms":["webonly"],"flows":[],"haserror s":false,"rootid":"xtcbb","updateid":"pnwf","ishidden":fal se,"islibrary":false,"installations":0,"runs":0,"librarydepe ndencyids":[],"art":0,"toptagids":[],"screenshotthumburl ":null,"screenshoturl":null}

26 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

27 User example.. {"kind":"user","id":"pboj","url":"http://www.t ouchdevelop.com/pboj","name":"TouchDevel op Samples","haspicture":true,"about":"Sample scripts written by the TouchDevelop team","features":667,"receivedpositivereview s":556,"subscribers":129,"score":1265}

28 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

29 {"kind":"comment","time": ,"id":"rjyk stvu","url":"http://www.touchdevelop.com/rjykst vu","text":"Awesome :)","userid":"pboj","username":"TouchDevelop Samples","userscore":1265,"userhaspicture":true,"publicationid":"bgxdjdlb","publicationname":"D raw3D","publicationkind":"script","nestinglevel": 1,"positivereviews":0,"subscribers":0,"comments ":0}

30 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 ♥

31 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

32 Other JSON objects… screenshot art leaderboardscore document

33 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

34 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]

35 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

36 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]

37 Examples: /api/ecvs for the info about script with id /ecvs; status code 404 if no such script id /api/ecvs /api/ecvs/text for the raw text of the script with id /ecvs; status code 404 if no such script id /api/ecvs/text /api/ecvs/ast for the compiled abstract syntax tree of /ecvs; status code 404 if no such script id /api/ecvs/ast /api/fhxu/base for the base script of /fhxu; status code 404 if no base exists /api/fhxu/base /api/pboj/scripts for a list of all scripts by the user /pboj /api/pboj/scripts /api/pboj/comments for a list of all comments by the user /pboj /api/pboj/comments /api/pboj/screenshots for a list of all screenshots by the user /pboj /api/pboj/screenshots /api/pboj/reviews for a list of all reviews by the user /pboj /api/pboj/reviews /api/pboj/leaderboardscores for a list of all leaderboard scores by the user /pboj /api/pboj/leaderboardscores

38 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]

39 Batch request example.. HTTP Request: GET If-None-Match: $hash Encoded JSON as: { "method": "GET", "relative_url": "$path", "If-None-Match": "$hash" }

40 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" }

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

42 Conventions..  experimental research features.  under heavy development.  No access restrictions. http, rest, json  All APIs are exposed as REST services; the APIs return structured JSON objects.

43 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.

44 Examples.. /api/clhb/run/fibonacci?$x=3  call the action “fibonacci” from the script Fibonacci algorithm /clhb 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 Currency exchange /irdk  Passing “JPY” and “RUB” as arguments for “from” and “to” respectively.

45 “Arguments when not supplied takes corresponding default values. Parameter kinds supported are:  Boolean  Number  String  DateTime If any other kind, the execution engine assigns the corresponding default values.”[3]

46 Response format If successful: { "success": true, "result": [result1, result2, …] } If unsuccessful: { "success": false, "error": errorMsg }

47 Example.. Action request to the cloud: /api/irdk/run/get%20rates?$from=JPY&$to=RUB Successful response returned: { success: true, result: [true, ] }

48 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" }

49 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]

50 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]

51 References [1] [2] https://www.touchdevelop.com/help/cloudserviceshttps://www.touchdevelop.com/help/cloudservices [3] https://www.touchdevelop.com/help/cloudexecutionhttps://www.touchdevelop.com/help/cloudexecution


Download ppt "JSON TouchDevelop cloud service API JSON TouchDevelop cloud service API TouchDevelop cloud execution API TouchDevelop cloud execution API."

Similar presentations


Ads by Google