Media Services operations REST API overview
The Media Services Operations REST API is used for creating Jobs, Assets, Live Channels and other resources in a Media Services account. For more information, see Media Services Operations REST API reference.
Media Services provides a REST API that accepts both JSON or atom+pub XML format. Media Services REST API requires specific HTTP headers that each client must send when connecting to Media Services, as well as a set of optional headers. The following sections describe the headers and HTTP verbs you can use when creating requests and receiving responses from Media Services.
Authentication to the Media Services REST API is done through Azure Active Directory authentication which is outlined in the article Use Azure AD authentication to access the Azure Media Services API with REST
Considerations
The following considerations apply when using REST.
When querying entities, there is a limit of 1000 entities returned at one time because public REST v2 limits query results to 1000 results. You need to use Skip and Take (.NET)/ top (REST) as described in this .NET example and this REST API example.
When using JSON and specifying to use the __metadata keyword in the request (for example, to reference a linked object) you MUST set the Accept header to JSON Verbose format (see the following example). Odata does not understand the __metadata property in the request, unless you set it to verbose.
POST https://media.windows.net/API/Jobs HTTP/1.1 Content-Type: application/json;odata=verbose Accept: application/json;odata=verbose DataServiceVersion: 3.0 MaxDataServiceVersion: 3.0 x-ms-version: 2.19 Authorization: Bearer <ENCODED JWT TOKEN> Host: media.windows.net { "Name" : "NewTestJob", "InputMediaAssets" : [{"__metadata" : {"uri" : "https://media.windows.net/api/Assets('nb%3Acid%3AUUID%3Aba5356eb-30ff-4dc6-9e5a-41e4223540e7')"}}] . . .
Standard HTTP request headers supported by Media Services
For every call you make into Media Services, there is a set of required headers you must include in your request and also a set of optional headers you may want to include. The table below lists the required headers:
| Header | Type | Value |
|---|---|---|
| Authorization | Bearer | Bearer is the only accepted authorization mechanism. The value must also include the access token provided by Azure Active Directory. |
| x-ms-version | Decimal | 2.17 (or most recent version) |
| DataServiceVersion | Decimal | 3.0 |
| MaxDataServiceVersion | Decimal | 3.0 |
Note
Because Media Services uses OData to expose its REST APIs, the DataServiceVersion and MaxDataServiceVersion headers should be included in all requests; however, if they are not, then currently Media Services assumes the DataServiceVersion value in use is 3.0.
The following is a set of optional headers:
| Header | Type | Value |
|---|---|---|
| Date | RFC 1123 date | Timestamp of the request |
| Accept | Content type | The requested content type for the response such as the following: -application/json;odata=verbose - application/atom+xml Responses may have a different content type, such as a blob fetch, where a successful response contains the blob stream as the payload. |
| Accept-Encoding | Gzip, deflate | GZIP and DEFLATE encoding, when applicable. Note: For large resources, Media Services may ignore this header and return noncompressed data. |
| Accept-Language | "en", "es", and so on. | Specifies the preferred language for the response. |
| Accept-Charset | Charset type like “UTF-8” | Default is UTF-8. |
| X-HTTP-Method | HTTP Method | Allows clients or firewalls that do not support HTTP methods like PUT or DELETE to use these methods, tunneled via a GET call. |
| Content-Type | Content type | Content type of the request body in PUT or POST requests. |
| client-request-id | String | A caller-defined value that identifies the given request. If specified, this value will be included in the response message as a way to map the request. Important Values should be capped at 2096b (2k). |
Standard HTTP response headers supported by Media Services
The following is a set of headers that may be returned to you depending on the resource you were requesting and the action you intended to perform.
| Header | Type | Value |
|---|---|---|
| request-id | String | A unique identifier for the current operation, service generated. |
| client-request-id | String | An identifier specified by the caller in the original request, if present. |
| Date | RFC 1123 date | The date/time that the request was processed. |
| Content-Type | Varies | The content type of the response body. |
| Content-Encoding | Varies | Gzip or deflate, as appropriate. |
Standard HTTP verbs supported by Media Services
The following is a complete list of HTTP verbs that can be used when making HTTP requests:
| Verb | Description |
|---|---|
| GET | Returns the current value of an object. |
| POST | Creates an object based on the data provided, or submits a command. |
| PUT | Replaces an object, or creates a named object (when applicable). |
| DELETE | Deletes an object. |
| MERGE | Updates an existing object with named property changes. |
| HEAD | Returns metadata of an object for a GET response. |
Discover and browse the Media Services entity model
To make Media Services entities more discoverable, the $metadata operation can be used. It allows you to retrieve all valid entity types, entity properties, associations, functions, actions, and so on. By adding the $metadata operation to the end of your Media Services REST API endpoint, you can access this discovery service.
/api/$metadata.
You should append "?api-version=2.x" to the end of the URI if you want to view the metadata in a browser, or do not include the x-ms-version header in your request.
Authenticate with Media Services REST using Azure Active Directory
Authentication on the REST API is done through Azure Active Directory(AAD). For details on how to get required authentication details for your Media Services account from the Azure Portal, see Access the Azure Media Services API with Azure AD authentication.
For details on writing code that connects to the REST API using Azure AD authentication, see the article Use Azure AD authentication to access the Azure Media Services API with REST.