Skip to content

API

Jump to bottom Edit New page
Skye Shaw edited this page Dec 13, 2016 · 8 revisions

The API is currently under active development and has not been officially released

All responses have a content type of application/json.

Response Objects

Job

Represents a Transporter GUI job. Here's an example for a queued, upload job:

{
  "id": 112,
  "type": "upload"
  "state": "queued",
  "options": {
	"package": "/some/package.itmsp",
	"delete": false,
	"username": "fofinha123",
	"password": "shhhhh!",
	"shortname": "sshaw",
	"batch": null
  },
  "result": null,
  "exceptions": null,
  "created_at": "2016-11-19T20:01:07.373Z",
  "updated_at": "2016-11-19T20:01:07.373Z",
  "priority": "normal",
  "account_id": 12,
  "disable_notification": false
}

Here's one for a failed verify job:

{
  "id": 105,
  "type": "verify",
  "state": "failure",
  "options": {
	"package": "/Users/sshaw/Desktop/982345323555.itmsp",
	"batch": true,
	"verify_assets": false,
	"username": "user@example.com",
	"password": "123",
	"shortname": "shorty"
  },
  "result": null,
  "exceptions": "Feature is missing a checksum (5011), Playlist already exits for this UPC (3005), Bad chapter timecode (4009), Preorder date must be before available date (4019)",
  "created_at": "2016-09-04T00:54:24.205Z",
  "updated_at": "2016-09-25T02:48:06.575Z",
  "priority": "normal",
  "account_id": 15,
  "disable_notification": false
}
Properties
  • id - job's id
  • type - one of lookup, providers, schema, status, upload, verify, version
  • state - one of queued, running, success, failure
  • options - arguments passed to iTMSTransporter, this varies based on the job's type, see Endpoints below
  • result - the results of a successful job, this varies based on the job type
  • exceptions - why the job failed
  • disable_notification - email notification's are enabled/disabled for the job

Errors

Error responses with a non-HTTP 2XX status are considered errors. With the exception of a HTTP 422 (see below) error responses contain a single property error, whose value contains the error message:

{"error":"Not found"}

With HTTP 422 response, each property is a request property and its value is an array that contains the reasons why the give property was invalid. For example:

{
  "account_id": [
	"unknown"
  ],
  "package": [
	"must end with \".itmsp\""
  ]
}

The property base (not shown) refers to the request itself and not a specific property.

Priorities

Certain jobs accept a priority, this specifies the priority in which they'll be processed by itmsworker. Valid priorities are: normal, high, low, next.

A priority of next will put the job at the front of the queue (well, assuming there isn't another job with next priority in front of it).

Endpoints

Providers

Create a job to retrieve the metadata for a previously uploaded package.

  • Endpoint: /api/lookup
  • Method: POST
Request
  • package_id: The type of identifier used to lookup the metadata, must be vendor_id or apple_id
  • package_id_value: The identifier
  • account_id: The Transporter GUI ID of the account to use to request the package's
  • priority: Optional, job priority, defaults to "normal". See Job Priorities.
Response

See Response Objects.

Sample
curl -i -H 'content-type: application/json' -XPOST 'http://localhost:3000/api/lookup' -d '{
  "package_id": "vendor_id",
  "package_id_value": "X123999",
  "account_id": 12
}
'

Providers

Create a job that will retrieve a list of providers for which account_id has permission to deliver content.

  • Endpoint: /api/providers
  • Method: POST
Request
  • account_id: The Transporter GUI ID of the account to use to request the package's
  • priority: Optional, job priority, defaults to "normal". See Job Priorities.
Response

See Response Objects.

Sample
curl -i -H 'content-type: application/json' -XPOST 'http://localhost:3000/api/providers' -d '{
  "account_id": 12
}
'

Schema

Create a job to retrieve a metadata schema.

  • Endpoint: /api/schema
  • Method: POST
Request
  • version_name: Type of schema, either film or tv.
  • version_number: Schema version
  • type: Schema type, either strict or transitional
  • account_id: The Transporter GUI ID of the account to use to request the package's status
  • priority: Optional, job priority, defaults to "normal". See Job Priorities.
Response

See Response Objects.

Sample

curl -i -H 'content-type: application/json' -XPOST 'http://localhost:3000/api/schema' -d '{
  "version_name": "film",
  "version_number": "5.9",
  "type": "strict",
  "account_id": 12
}
'

Status

Create a job to check an previous upload's status.

  • Endpoint: /api/status
  • Method: POST
Request
  • vendor_id: ID of the package to perform a status request on
  • account_id: The Transporter GUI ID of the account to use to request the package's status
  • priority: Optional, job priority, defaults to "normal". See Job Priorities.
Response

See Response Objects.

Sample
curl -i -H 'content-type: application/json' -XPOST 'http://localhost:3000/api/status' -d '{
  "vendor_id": "X123999",
  "account_id": 12
}
'

Upload

Create an upload package job.

  • Endpoint: /api/upload
  • Method: POST
Request

All paths must be accessible by the worker process.

  • package: Absolute path of the package to upload
  • disable_notification: optional, disable email notifications for this job only
  • rate: Optional, transfer rate in kbps
  • batch: Optional, batch upload, defaults to false
  • success: Optional, absolute path of a directory to move package to if the upload succeeds
  • failure: Optional, absolute path of a directory to move package to if the upload fails
  • priority: Optional, job priority, defaults to "normal". See Job Priorities.
  • account_id: The Transporter GUI ID of the account to use to upload the package
  • delete: Optional, defaults to false:
  • transport: Optional, defaults to ITMSTrasnporter's default
Response

See Response Objects.

Sample
curl -i -H 'content-type: application/json' -XPOST 'http://localhost:3000/api/upload' -d '{
  "package": "/path/to/package.itmsp",
  "account_id": 12,
  "transport": "Aspera"
}
'

Verify

Create a package verification job.

  • Endpoint: /api/verify
  • Method: POST
Request
  • package: Absolute path of the package to upload, must be accessible by the worker process
  • account_id: The Transporter GUI ID of the account to use to request the package's status
  • batch: Optional, batch verification, defaults to false
  • verify_assets: Optional, verify assets (normally only the metadata is verified), defaults to false
  • priority: Optional, job priority, defaults to "normal". See Job Priorities.
Response

See Response Objects.

Sample

curl -i -H 'content-type: application/json' -XPOST 'http://localhost:3000/api/verify' -d '{
  "package": "/path/to/package.itmsp",
  "account_id": 12
}
'

Made by ScreenStaring

Add a custom sidebar
Clone this wiki locally