tX API Example Usage
This page moved to https://forum.door43.org/t/door43-org-tx-development-architecture/65.
The tX conversion platform is available via an RESTful API. First, we'll cover authentication, then show examples of using the API.
tX uses HTTP Basic Auth over HTTPS. You'll need to submit your Door43 username and password credentials with every request.
We plan to support Gogs user tokens eventually. You may generate a token by signing in to your git.door43.org account, click the down arrow in the upper right (next to your avatar), select "Your Settings". Click on "Applications" in the left hand bar, then select "Generate New Token". Name the token "tX" and click "Generate Token". Your token will be displayed at the top of the page in a light blue box (it will look something like 'd075e12826a327437800b882ae8724120b060f1a') . Record it in a safe location for your use.
Perform a GET request against https://api.door43.org/tx to determine what endpoints and methods are allowed.
Request:
GET https://api.door43.org/tx
Response:
200 OK
{
"version": "1",
"links": [
{
"href": "https://api.door43.org/tx/job",
"rel": "list",
"method": "GET"
},
{
"href": "https://api.door43.org/tx/job",
"rel": "create",
"method": "POST"
},
...
To list your jobs, perform the following example. Note that if you haven't created any jobs yet then your list will be empty.
Request:
GET https://api.door43.org/tx/job?user_token=<gogs_user_token>
or
POST https://api.door43.org/tx/job
{ "user_token": "<gogs_user_token>" }
Response:
200 OK
{
"job": [
{
"job_id": "b2df28c8-7696-11e6-a03d-278f51ff8a84",
"created_at": "2016-12-27T16:32:00Z",
"eta": "2016-12-27T16:33:00Z",
"callback": "https://your.url/for_job_complete_update",
"resource_type": "obs",
"input_format": "md",
"output_format": "pdf",
"options": {
"line_spacing": "120%"
},
"links": [
{
"href": "https://api.door43.org/tx/job/f9912771-768b-11e6-9f9b-2bbf72889dc8",
"rel": "self"
"method": "GET"
}
]
}
]
"links": [
{
"href": "https://api.door43.org/tx/job",
"rel": "create",
"method": "POST"
}
]
}
Your request should contain a link to the source file(s) to be converted. The tX app will use these link to get the source content to be converted. Eventually, some time of multi-part POST will be accepted, which will allow you to send your data with your request. In this case, the first part should contain the binary representation of the data to be converted and the second part should contain a JSON object with your requested conversion options.
You may provide a callback URL, which should be an endpoint that you want tX to make a POST request to that will notify your code that the conversion job is complete. This is optional, your client is also free to GET the output URL as many times as you like until the content is available.
An example of the JSON object may be seen below (user_token can be in the URL or the JSON payload):
Request:
POST https://api.door43.org/tx/job?user_token=<gogs_user_token>
{
"user_token": "<gogs_user_token>",
"resource_type": "obs",
"input_format": "md",
"output_format": "pdf",
"source": "https://git.door43.org/username/project/archive/master.zip",
"callback": "https://your.url/for_job_complete_update",
"options": {
"line_spacing": "120%"
}
}
Response:
201 Created
{
"job": {
"job_id": "b2df28c8-7696-11e6-a03d-278f51ff8a84",
"created_at": "2016-12-27T16:32:00Z",
"eta": "2016-12-27T16:33:00Z",
"source": "https://git.door43.org/username/project/archive/master.zip",
"callback": "https://your.url/for_job_complete_update",
"resource_type": "obs",
"input_format": "md",
"output_format": "pdf",
"output": "https://cdn.door43.org/tx/jobs/b2df28c8-7696-11e6-a03d-278f51ff8a84.zip",
"output_expiration": "2016-12-28T16:32:00Z",
"options": {
"line_spacing": "120%"
},
"status": "requested",
"success": null,
"links": [
{
"href": "https://api.door43.org/tx/job/b2df28c8-7696-11e6-a03d-278f51ff8a84",
"rel": "self"
"method": "GET"
}
]
},
"links": [
{
"href": "https://api.door43.org/tx/job",
"rel": "list",
"method": "GET"
},
]
}
Note that if you specify invalid options in your request then you will receive a 400 Bad Request response with a JSON payload similar to:
Response
{
"errorMessage": "resource_type unknown",
}
To get the output from your conversion job, simply make a request to the output URL recorded above. If the document is not available yet then the server will return a 404 Not Found message.
If you provided a callback URL then tX will notify your code when the output file is available with a JSON in the body of a POST to your callback such as the following:
{
"job_id": "b2df28c8-7696-11e6-a03d-278f51ff8a84",
"identifier": "<the unique identifier you sent in the job request if you specified one>",
"success": true, # true = was able to convert files even if had warnings, false = failed to convert
"status": "success", # See "Job Status"
"message": "Converted successful", # A message about the status
"output": "https://cdn.door43.org/tx/jobs/b2df28c8-7696-11e6-a03d-278f51ff8a84.zip",
"output_expiration": "2016-12-28T16:32:00Z",
"log": ['Started converstion', ..., "Completed conversion"],
"warnings": [],
"errors": [],
"created_at": "2016-12-27T16:32:00Z",
"started_at": "2016-12-27T16:32:21Z",
"ended_at": "2016-12-27T16:33:13Z"
}