REST-based service API

overview

All TouchDevelop scripts are stored and analyzed in the cloud. For research purposes, TouchDevelop exposes a set of web services to query scripts, users, comments, screenshots, reviews, leaderboard scores, and tags.

disclaimer

The TouchDevelop Cloud Services Agreement applies for the APIs described below.

revisions

The design of the web services is still under heavy development.

The APIs may change at any time without notice.

Recent changes:
2012-02-09: Completely new set of streamlined APIs under /api/ path.
2012-03-15: /api/[scriptid]/text now returns script text formatted according to latest internal language syntax; use optional ?original=true parameter to get old behavior.
2012-04-03: New APIs /api/[...]/subscribers, /api/[...]/subscriptions, /api/[...]/notifications, properties haspicture, subscribers
2012-04-27: New APIs /api/tags, /api/[tagid]/scripts, /api/[scriptid or userid]/tags, /api/[userid]/tagged/[tagid], kind tag, and properties userscore, userhaspicture, screenshots
2012-05-03: Most APIs now support ETag/If-None-Match headers; property now removed from lists; beginning of time redefined
2012-05-07: Renamed &text=... parameter to &q=... which is now supported in several APIs.
2012-06-04: New APIs /api/[userid]/reviewed/[scriptid or commentid]
2012-06-28: New APIs /api/[scriptid]/leaderboardscores, /api/[userid]/leaderboardscored/[scriptid]
2012-07-11: New batch API /api; new optional query parameter for lists: etagsmode
2012-08-02: New API /api/[userid]/tagged/[scriptid]
2012-08-14: Added librarydependencyids and toptagids as script properties
2012-08-16: Added optional return_ssl_resources parameter
2012-10-15: Added optional recent parameter for /api/[userid]/leaderboardscored/[scriptid], /api/[scriptid or userid]/leaderboardscores
2012-11-08: New APIs /api/[artid], /api/art, /api/[userid]/art queries and a new art kind
2012-11-20: New APIs /api/[artid]/scripts, /api/[scriptid]/art; added art as script property
2012-11-29: New APIs /api/documents; new document kind
2012-12-11: Added wavurl and aacurl as art properties
2013-01-31: Added documentation for feature properties
2013-03-08: Added userplatform properties
2013-03-21: Added API /api/stats
2013-07-10: Updated documentation for feature properties; new APIs /api/features, /api/[userid or scriptid]/features
2013-08-01: New APIs /api/runs, /api/runbuckets, /api/[scriptid]/runbuckets, /api/[runbucketid or userid]/runs, /api/[scriptid]/webast, /api/[scriptid]/coverage, /api/[scriptid]/profile; deprecated /api/[scriptid]/ast; new run and runbucket document kinds 2013-10-18: New APIs /api/webapps; webapp document kind 2013-12-05: Removed API /api/[scriptid]/ast

conventions

http, rest, json

All APIs are exposed as REST services; the 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.

access restrictions

At this time, no authentication is required to invoke the APIs described below.

search query strings

See here for more documentation on the search query syntax: how to search.

count, continuation

When querying a list, you will get the results in batches. You can add the query parameter &count=[count] with a number between 10 and 1000 to indicate how many items you would like to get returned in each batch. However, the actually returned number of items may be different. You can add the query &applyupdates=true if you want that the latest update of all scripts is returned. The structured JSON response may contain a field called continuation. If this continuation token contains a non-empty string, then there might be more items available, which you can get by performing the exact same query again with the added 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. Publication ids are sequences of lower-case latin letters, at least four letters long. The ids are randomly assigned by TouchDevelop; the space of possible ids is only used sparcely. Do not try to guess ids; instead, use the APIs to enumerate assigned ids.

APIs

main lists

The following queries return lists that enumerate all available objects.

The following queries return lists that enumerate a particular subset of all available objects.

Examples:

publication properties

Given a publication id, you can query certain properties: You can get the script text, or its compiled abstract syntax tree by querying /api/[scriptid]/text and /api/[scriptid]/webast. As the TouchDevelop language is evolving, the returned script text might changed. Use /text?original=true to obtain the script text as it was originally submitted.

Examples:

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

script

user

comment

screenshot

review

tag

art

leaderboardscore

document

feature

run

run bucket

web app

ETag/If-None-Match headers

Every successful response contains an ETag header representing a stable hash derived form 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.

Using ETags in list queries

The optional query parameter &etagsmode=[etagsmode] for list queries can be used to reduce the data transfers required to perform queries and responses. The etagsmode can be one of the following.

Examples:

To further reduce data transfers for requests with rarely changing responses, e.g. featured-scripts, you can indicate in the query that you already have obtained the information about a publication earlier. You do so by appending the etagsmode with a comma followed by a comma-separated list of id:ETag pairs.

Examples:

If the query string gets long, or you want that it gets compressed, wrap the request in a batch request.

batch requests

You can bundle requests. Bundling involves encoding HTTP requests and responses in JSON form.

To perform a batch request, do a POST request to /api, with a JSON body containing a batch of requests. Unless the JSON body is malformed or there is a fundamental problem with the HTTP request, the main /api call should always return with a 200 OK, while all individual sub-requests have their own status codes embedded in a response JSON object.

At this time, a batch request may include at most 50 individual requests.

batch JSON form of basic HTTP request

An HTTP request similar to

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

is encoded in JSON as follows.

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

The "method" field can be omitted and then "GET" will be assumed as the method. An HTTP response similar to

        200 OK
        ETag: $hash
        $json
    

is encoded in JSON as follows.

        { "code": 200, "body": $json, "ETag": "$hash" }
    

batch array of requests

You can bundle an array of requests [ $request1, $request2, ..., $requestN ], where each $requestI is given in JSON-encoded form, as follows.

        { "array": [ $request1, $request2, ..., $requestN ], 
          "If-None-Match": "$hash" }
    

Responses come in array form as well.

        { "code": 200, 
          "array": [ $response1, ..., $responseN ], 
          "ETag": "$hash" }
    

Note that such array requests and responses work with ETag/If-None-Match just as individual requests.

limitations

Not all URLs are supported for batch requests yet. Not yet supported APIs are:

coverage and profile information

You can query aggregated coverage and profile information as follows. The current compilerversion is 0.

Each query returns a JSON array containing objects of one of the following kinds.

coverage for view=union and view=intersection

coverage for view=sum

profile to no view and view=normalized

profile for view=unithistogram

statistics

You can query global statistics as follows.

It returns a JSON object with the following fields.

ssl

All queries can be performed via either http or https.

By default, all returned resources (redirections, and urls embedded in JSON objects) will refer to the same protocol as the request protocol. This default can be changed by appending either &return_ssl_resources=1 or &return_ssl_resources=0 to the query. In case of a batch request, the parameter must be added to the outer /api batch request, and it then also applies to all nested queries; overriding the default within nested batch queries is not supported.

faq

real-time updates

You can receive realtime updates to your own server whenever publications are created or deleted.

RSS feeds

You can subscribe to RSS feeds to poll for updates.

more information