Warpwire's technology runs on its own RESTful API.
This guide is intended for software developers and IT administrators who want to provide deep systems integration with Warpwire. It provides general information on the programmatic creation of objects via the REST API, data conventions, and integrating and merging with existing datasets. Understanding the basic Warpwire conventions will help you provide an optimal integration experience for your users.
This document is divided into sections that reflect each of the external data management layers that Warpwire provides. Warpwire leverages web standards for API communication, uses SSL for all data transmission and encryption, and provides access control levels for every API call.
Warpwire also integrates with an organization's Single Sign-On (SSO) system to provide both user authentication and authorization. Specifics regarding SSO integration are provided in additional specification guides and are outside the scope of this document. Warpwire uses a REST-ful style interface utilizing both REST nouns and verbs.
Warpwire uses a few simple conventions throughout the entire API to ensure that operations are both consistent and predictable. There are a few API calls that deviate from these conventions — these deviations are explicitly noted. The following section lists the Warpwire nomenclature that is used throughout this document:
UUID — All objects are automatically assigned a Universally Unique Identifier (UUID). It is through this value that all objects are accessed. A UUID is guaranteed to be unique for every object within an organization and is analogous to a primary key.
Collection — A set of objects is stored in a collection. A collection can store both objects and additional collections. A collection is also commonly referred to as a "Media Library" in other end user documentation, however these terms are synonymous. Access control and permissions are managed on a collection basis where every item within a collection maintains the same permissions (see Permission section). If an object does not exist within a specified collection a 404 Not Found response is returned (see HTTP Response Codes for additional information).
If object A is a member of two different collections, C1 and C2, there is no guarantee that object A's permissions will be the same in both C1 and C2. However, you are guaranteed that every object within C1 and C2 will have the same base permissions.
UUID Specification — All UUIDs provided are assigned by the API upon object creation and follow the RFC 4122 version 5 specifications. All UUID's are in hexadecimal format and follow the pattern {8}-{4}-{4}-{4}-{16}, with dashes being optional. Most API GET request returns the object UUID as a response parameter.
Authentication Tokens — A token is expected to be supplied as a header request for every API call that is not public. If you make a private API call and do not provide an Authorization: OAuth header and accompanying token, the request will fail and return 401 Not Authorized. Please note that all tokens have expirations and must either be renewed or re-issued upon session expiration, user sign out, or token invalidation.
Most API calls follow this convention:
{ACTION}/c/{COLLECTION_UUID}/o/{OBJECT_UUID}
All requests that are non-public expect an Authorization: OAuth header. The API returns all data as an 8-bit UTF JSON encoded string. It is suggested that you also ensure that all input data is encoded in UTF-8 format to ensure maximum data consistency. Below is an example of a typical POST command using CURL.
curl https://api.example.com/api/describe/c/ABCDEF-1234-CDEF-5678-ABCDEF0123456789/o/CCCBBB-1234-CDEF-5678-ABCDEF0123456789/ -H 'Authorization: OAuth c4eFFFwnmnGIbud1Bxyyzmg4yHmD9D92DJhlWNIib' -X POST -d "title=My+first+title" –v
Warpwire utilizes most of the HTTP methods including GET, POST, PUT, DELETE, OPTIONS, and HEAD. For clients that do not support a specific method such as DELETE or PUT, you should use the POST method and include a POST data variable named "_METHOD" with the value being the type of method in question (see the example below). Alternatively, you can also use the X-HTTP-Method-Override header directive to specify the missing method. Warpwire recommends that you use the CURL library as it supports the entire set of HTTP methods.
HTTP/1.1 {URL} POST
<input type="hidden" name="_METHOD" value="DELETE">
Warpwire uses the HTTP methods as follows:
GET — Returns JSON-encoded data for the supplied URL. The GET method expects the URL to include both the complete path for the resource and the identifying resource information (e.g. collection UUID). The GET command will always return a JSON-encoded object or the empty set if no data is returned. It also returns a corresponding HTTP response code that indicates the status of the transaction (i.e. 200 OK indicates a successful request and 400 Bad Request indicates a malformed request). Please see the HTTP Response
Codes section for more information.
PUT — Used to create a new object. This method will return a HTTP 201 Created response upon the successful creation of a resource. Additionally, if the user does not have permission to issue the PUT call for a particular collection, the call will return a HTTP 403 Forbidden header. Please note that since you cannot manually assign a universally unique identifier for an object, re-issuing a PUT request will result in the creation of a new object.
POST — Used to update any existing object. This method will return a HTTP 202 Accepted response upon the successful modification of a resource. The POST command expects the URL to only contain information necessary to access the resource, such as the collection UUID and object UUID. All other parameters must be specified in the POST data fields. Note that some parameters can only be issued via the initial PUT request and cannot be changed via a POST request. If the user does not have permission to issue the POST command for a particular collection, the method will return a HTTP 403 Forbidden response.
DELETE — Removes a resource. This method will return a HTTP 200 OK response upon the successful deletion of a resource. The DELETE method is not available for most API calls. If the user does not have permission to issue the DELETE command for a particular collection, the method will return a HTTP 403 Forbidden response.
OPTIONS — Return 200 OK for most calls that issue this request. This call is used in conjunction with all pre-flight Cross-origin resource sharing (CORS) calls. If you are using the API via CURL (or other command line tools) it is not necessary to supply the OPTIONS call. For time consuming operations such as uploading, the OPTIONS method will return proper response information that should be used to determine if the operation should proceed (e.g. the user is not currently authenticated to perform the request). If you are calling the API via AJAX requests within a web browser, you must comply with all CORS requirements. Therefore, you must ensure that the server making the requests has been added to the allowed list of servers that may perform a Access-Control-Allow-Origin request.
Describe is the most basic and important Warpwire API call. You can think of a describe API call as a mobile phone's address book that provides basic metadata and routing information for a contact. The describe call is public and does not require any user authentication (nor the need to supply the Authorization: OAuth header). However, a public request will only a return a limited subset of data about an object while an authenticated call will return the complete record.
GET Method:
/api/describe/c/[collection_uuid]/o/[object_uuid]/
Request — The GET request must be in the following format.
| Attribute | Description |
|---|---|
| collection_uuid (required) | A valid collection UUID resource. |
| object_uuid (required) | A valid object UUID resource. |
Response — For any GET request the following information can be returned in a JSON formatted object.
| Attribute | Description |
|---|---|
| type | A textual version of the type of resource. This could include "catalog", "video", "audio", "file", etc. |
| title | The title of the resource. A title may be blank or can be up to 255 characters in length. |
| images | An array of images that accompany the object. Please note that the images array may be an empty set. |
| images.thumbnail | A 128x128 pixel image of the resource (if available). |
| images.square | A 512x512 pixel image of the resource (if available). |
| images.large | A 1280x760 pixel image of the resource (if available). |
| public | Should this resource be available to the public? The values can include either "true" or "false". Default value is "false". |
| metadata | An array of metadata associated with the object. This could include additional information such as duration, or the empty set. |
| description | Textual description of the object. This may be blank. |
| properties | An array of properties that accompany the object. This could be an empty set. |
| uuid | The universally unique identifier of the object. |
| userId | Identifier of user who created the resource. This information is not informative without performing an additional user API call. |
| authenticated | Indicates if the current user is authenticated. Value is either "true" or "false". |
| permLink | A permanent shortened URL that a user can access the resource. |
| created | An Epoch timestamp of the date the object was created. |
| modified | An Epoch timestamp of the date the object was modified. |
PUT Method:
/api/describe/c/[collection_uuid]/o/0/
Request — Adds an object to an existing collection. Any parameter not specified in the URL above must be submitted as a PUT data field. For any PUT request the following information may be provided.
| Attribute | Description |
|---|---|
| collection_uuid (required) | A valid collection UUID resource. If the resource is 0 a new collection will be created. |
| type (required) | A textual version of the type of resource. This could include "catalog", "video", "audio", "file", etc. |
| title | The title of the resource. A title may be blank or can be up to 255 characters in length. |
| public | Should this resource be available to the public? The values can include either "true" or "false". Default value is "false". |
| description | Textual description of the object. This may be blank. |
| duration | The duration of the media object in seconds. |
Response — The following response is returned for the PUT request as a JSON encoded object.
| Attribute | Description |
|---|---|
| uuid | The universally unique identifier of the object. |
POST Method:
/api/describe/c/[collection_uuid]/o/[object_uuid]/
Request — Updates an object. Any parameter not specified in the URL above must be submitted as a POST data field. For any POST request the following information can be provided.
| Attribute | Description |
|---|---|
| collection_uuid (required) | A valid collection UUID resource. |
| object_uuid (required) | A valid object UUID resource. |
| type (required) | A textual version of the type of resource. This could include "catalog", "video", "audio", "file", etc. |
| title | The title of the resource. A title may be blank or can be up to 255 characters in length. |
| public | Should this resource be available to the public? The values can include either "true" or "false". Default value is "false". |
| description | Textual description of the object. This may be blank. |
| duration | The duration of the media object in seconds. |
Response — The following response is returned for the POST request as a JSON encoded object.
| Attribute | Description |
|---|---|
| uuid | The universally unique identifier of the object. |
The user API call is used to get information about a particular user. The user API call requires user authentication and is not public. Additionally, based on the user’s permission level, a subset of information regarding the user may be returned.
GET Method:
/api/user/c/[collection_uuid]/o/[user_id]/
Request — For any GET request the following information must be provided.
| Attribute | Description |
|---|---|
| collection_uuid (required) | A valid collection UUID resource. |
| user_id (required) | A valid user identifier. If this value is 0, it will return the user information for the currently authenticated user. |
Response — For any GET request the following information can be returned.
| Attribute | Description |
|---|---|
| firstName123 | The requested user’s first name. |
| lastName123 | The requested user’s last name. |
| userId12 | The requested user’s identifier. |
| uniqueId12 | The requested user's SSO unique identifier. |
| {parameters} | Additional parameters that are stored about the user. |
1 — Provided to the currently authenticated user if they are making a self request
2 — Provided to the an administrator of a collection the userId is a member
3 — Provided to all authenticated and authorized users
POST Method:
/api/user/c/[collection_uuid]/o/[user_id]/
Request — Updates a user. For any POST request the following information can be provided.
| Attribute | Description |
|---|---|
| collection_uuid (required) | A valid collection UUID resource. |
| user_id (required) | The requested user’s identifier. If this value is 0, the uniqueId POST data field is required. |
| firstName | The requested user’s first name. |
| lastName | The requested user’s last name. |
| uniqueId (conditional) | The requested user’s SSO unique identifier. Required if the user_id field is 0. |
Response — For any POST request the following information is provided.
| Attribute | Description |
|---|---|
| userId | The user identifier. |
The group API call returns information regarding groups. The group API call requires authentication.
GET Method:
/api/group/q/[QUERY]/
Request — This will search all existing groups for the submitted query. For any GET request the following information can be provided.
| Attribute | Description |
|---|---|
| query (required) | What will be used to search users or groups and return matching ones. |
| type | A valid item type. Can be either 'user' or 'group'. If no type is specified, it will default to 'group.' |
Response — For any GET request the following information can be returned. This call will return an array of objects that contain the properties specified below, or the empty set.
| Attribute | Description |
|---|---|
| object_id | The object identifier associated with the result. This is Warpwire's internal unique reference. |
| name | The name associated with the result. |
| type | The type associated with the result, this will either be 'user' or 'group.' |
GET Method:
/api/group/u/[UNIQUE_ID]/
Request — If you know the unique_id of the group, this call will retrive information about the group. For any GET request the following information must be provided.
| Attribute | Description |
|---|---|
| unique_id (required) | The query will return information about the group that matches the provided unique_id, if it exists. |
Response — For any GET request the following information can be returned. This call will return an array of objects that contain the properties specified below, or the empty set.
| Attribute | Description |
|---|---|
| objectId | The object identifier associated with the result. This is Warpwire's internal unique reference. |
| uniqueId | The unique identifier used by your organization to identify groups. |
| name | The name associated with the unique id. |
| externalProviderId | The external provider id is generally a secondary identifier from an external system (like an LMS). |
| link | Returns the Warpwire URL of the Media Library associated with the group. |
GET Method:
/api/group/e/[EXTERNAL_PROVIDER_ID]/
Request — This will search all existing groups for the submitted external provider identifier. For any GET request the following information must be provided.
| Attribute | Description |
|---|---|
| external_provider_id (required) | The query will return information about the group that matches the provided external_provider_id, if it exists. |
Response — For any GET request the following information can be returned. This call will return an array of objects that contain the properties specified below, or the empty set.
| Attribute | Description |
|---|---|
| objectId | The object identifier associated with the result. This is Warpwire's internal unique reference. |
| uniqueId | The unique identifier used by your organization to identify groups. |
| name | The name associated with the unique id. |
| externalProviderId | The external provider id is generally a secondary identifier from an external system (like an LMS). |
| link | Returns the Warpwire URL of the Media Library associated with the group. |
POST Method:
/api/group/u/[CURRENT_UNIQUE_ID]/
Request — This will update an existing group record, based on the group's current_unique_id. For any POST request the following information must be provided.
| Attribute | Description |
|---|---|
| current_unique_id (required) | The current unique indentifier. |
| objectId | The object identifier associated with the current_unique_id. This is Warpwire's internal unique reference. |
| uniqueId | The unique identifier used by your organization to identify groups. |
| name | The name associated with the unique id. |
| externalProviderId | The external provider id is generally a secondary identifier from an external system (like an LMS). |
| link | The Warpwire URL of the Media Library associated with the group. |
| hidden | This is a boolean value. Options are 'true' and 'false.' If 'true', the group will not appear in any search results. |
Response — For POST requests a HTTP 202 status code is returned. There is no other information provided in the response.
PUT Method: (creating a group)
/api/group/
Request — This will create a new group. For any PUT request the following information must be provided. Pass the following attibutes in the body of the request.
| Attribute | Description |
|---|---|
| objectId | The object identifier associated with the current_unique_id. This is Warpwire's internal unique reference. |
| uniqueId (required) | The unique identifier used by your organization to identify groups. |
| name (required) | The name associated iwth the external provider id. |
| externalProviderId (required if uniqueId is not provided) | The external provider id is generally a secondary identifier from an external system (like an LMS). |
| link | The Warpwire URL of the Media Library associated with the group. |
| hidden | This is a boolean value. Options are 'true' and 'false.' If 'true', the group will not appear in any search results. |
Response — For PUT requests a HTTP 202 status code is returned. There is no other information provided in the response.
The metadata API call returns information regarding metadata. The metadata API call requires authentication.
GET Method: List all metadata profiles
/api/metadata/
Request — Will return a paginated list of all metadata. This call requires authentication and requires no specified parameters.
Response — The following response is returned for the GET request as a JSON encoded object. The format will be a paginated list of metadata profiles, each with the following attributes:
| Attribute | Description |
|---|---|
| id | Unique identifier used by Warpwire to track the profile. |
| name | Internal id of the attribute name (for dublin core it'll be dc:subject or itunes:category) should match chosen ontology. |
| uri | User specified link to metadata specification. |
| local_key | Will indicate type of profile: dublin_core or iTunes Podcast or user defined. |
| creation | Date the metadata profile was created. |
| attribute_count | How many attributes the metadata profile contains. |
POST Method: Add new metadata profile
/api/metadata/
Request — This call will create a new metadata profile. Must be authenticated as an institutional admin.
| Attribute | Description |
|---|---|
| name (required) | The name of the metadata profile you are creating. Must be unique. Send this in the body of the request. |
| active | Boolean true/false. If 'True,' the vocabulary term will display in the user interface. |
| uri | User specified link to metadata specification. |
Response — This POST request will return: Status 201 "Success created [profile_id]."
[Profile_id] is a unique interger assigned to the profile and will be used in other calls in place of name.
PUT Method: Update existing metadata profile
/api/metadata/[profile_id]/
Request — This call will update a metadata profile. Must be authenticated as an institutional admin.
| Attribute | Description |
|---|---|
| profile_id (required) | The id of the metadata profile you are updating. Put this in the URL, as above, this is given when you create the profile. |
| name (required) | The name you want to change the profile to. This is a user-specified parameter. |
| uri | User specified link to metadata specification. |
| active | Boolean true/false. If 'True,' the vocabulary term will display in the user interface. |
Response — This PUT request will return: Status 202 "Success modified [profile_id]."
[Profile_id] is a unique interger assigned to the profile and will be used in other calls in place of name.
GET Method: Retrieve specific profile
/api/metadata/[profile_id]
Request — This call will return details of a specified metadata profile. Must be authenticated.
| Attribute | Description |
|---|---|
| profile_id (required) | The id of the metadata profile you are querying. Put this in the URL, as specified above. This is a positive interger identifying the profile. It is given when you create the profile. |
| limit | Optional. Specify the number of objects per page of the response. Must be a positive interger. |
| page | Specify the page of results to return. |
Response — This request will return the following attributes for the specified profile:
| Attribute | Description |
|---|---|
| profile_id | Unique identifier used by Warpwire to track the profile. |
| name | Name of the metadata profile. |
| uri | User specified link to metadata specification. |
| local_key | Will indicate type of profile: dublin_core or iTunes Podcast or user defined. |
| creation | Date the metadata profile was created. |
| attribute_count | How many attributes the metadata profile contains. |
GET Method: Retrieve list of attributes for a specific profile
/api/metadata/[profile_id]/attributes/
Request — This call gets a list of all attributes for a specified metadata profile. Must be authenticated.
| Attribute | Description |
|---|---|
| profile_id (required) | The id of the metadata profile you are querying. Put this in the URL, as specified above. This is a positive interger identifying the profile. It is given when you create the profile. |
| limit | Optional. Specify the number of objects per page of the response. Must be a positive interger. |
| page | Specify the page of results to return. |
Response — This request will return a paginated array of information for the specified profile:
| Attribute | Description |
|---|---|
| profile_id | Unique identifier used by Warpwire to track the profile |
| name | Name of the metadata profile. |
| uri | User specified link to metadata specification. |
| local_key | Will indicate type of profile: dublin_core or iTunes Podcast or user defined. |
| attributes | An array containing fields for each attribute. The 'attributes' arrary contains the following information for each attribute: |
| attributes.attribute_id | Unique identifier used by Warpwire to track the attribute. This is a positive interger. |
| attributes.name | Internal id of the attribute name (for dublin core it'll be dc:subject or itunes:category) should match chosen ontology. |
| attributes.display | External name of profile attribute shown to the end user. |
| attributes.description | Description of the attribute, if present. |
| attributes.enforced | Boolean true/false. Is this vocabulary enforced? An enforced vocabulary requires that the user input for this field match one of the vocabulary items specified in the 'vocabularies' array. |
| attributes.required | Boolean true/false. Must this field be populated? If true, an error will result if metadata is submitted but this field is blank. |
| attributes.duplicates | Boolean true/false. Can more that one copy of this attribute exist? If true, then there can be multiple entries for the attribute. If false, there can only be one. (e.g. Library of Congress allows multiple subjects for books, iTunes Podcasts allow multiple categories) |
| attributes.vocabularies | An arrary containing vocabulary elements, if they exist. |
PUT Method: Update existing metadata profile attribute
/api/metadata/[profile_id]/attributes/[attribute_id]
Request — This call will update a metadata profile. Must be authenticated as an institutional admin.
| Attribute | Description |
|---|---|
| profile_id (required) | The id of the metadata profile you are updating. Put this in the URL, as above, this is given when you create the profile. |
| attribute_id (required) | The id of the metadata profile attribute you are updating. Put this in the URL, as above, this is given when you create the profile. |
| name (required) | internal id of the attribute name (for dublin core it'll be dc:subject or itunes:category) should match chosen ontology. |
| display | External name of profile attribute shown to the end user. |
| description | Description of the metadata attribute. |
| active | Boolean true/false. If 'True,' the vocabulary term will display in the user interface. |
| enforced | Boolean true/false. Is this vocabulary enforced? An enforced vocabulary requires that the user input for this field match one of the vocabulary items specified in the 'vocabularies' array. |
| duplicates | Boolean true/false. Can more that one copy of this attribute exist? If true, then there can be multiple entries for the attribute. If false, there can only be one. (e.g. Library of Congress allows multiple subjects for books, iTunes Podcasts allow multiple categories) |
| required | Boolean true/false. Must this field be populated? If true, an error will result if metadata is submitted but this field is blank. |
Response — This PUT request will return: Status 202 "Success modified [attribute_id]."
[Profile_id] and [attribute_id] are unique to the profile and will be used in other calls in place of name.
POST Method: Add new metadata profile attribute
/api/metadata/[profile_id]/attributes/
Request — This call will create a new metadata profile attribute. Must be authenticated as an institutional admin. All of the attributes listed below must be unique.
| Attribute | Description |
|---|---|
| name (required) | Internal id of the attribute name (for dublin core it'll be dc:subject or itunes:category) should match chosen ontology. |
| display (required) | External name of profile attribute shown to the end user. |
| enforced (required) | Boolean true/false. Is this vocabulary enforced? An enforced vocabulary requires that the user input for this field match one of the vocabulary items specified in the 'vocabularies' array. |
| duplicates (required) | Boolean true/false. Can more that one copy of this attribute exist? If true, then there can be multiple entries for the attribute. If false, there can only be one. (e.g. Library of Congress allows multiple subjects for books, iTunes Podcasts allow multiple categories) |
| required (required) | Boolean true/false. Must this field be populated? If true, an error will result if metadata is submitted but this field is blank. |
Response — This Post request will return: Status 201: Created as well as an array displaying the attribute you just created.
GET Method: Get specific metadata profile attribute
/api/metadata/[profile_id]/attributes/[attribute_id]
Request — This call will retrieve a specific metadata profile attribute. Must be authenticated as an admin.
| Attribute | Description |
|---|---|
| profile_id (required) | The id of the metadata profile you are updating. Put this in the URL, as above, this is given when you create the profile. |
| attribute_id (required) | The id of the metadata profile attribute you are updating. Put this in the URL, as above, this is given when you create the profile |
| limit | Optional. Specify the number of objects per page of the response. Must be a positive interger. |
| page | Specify the page of results to return. |
Response — This request will return a paginated array of information for the specified profile:
| Attribute | Description |
|---|---|
| attribute_id | Unique identifier used by Warpwire to track the attribute. This is a positive interger. |
| name | Internal id of the attribute name (for dublin core it'll be dc:subject or itunes:category) should match chosen ontology. |
| display | External name of profile attribute shown to the end user. |
| description | Description of the attribute, if present. |
| enforced | Boolean true/false. Is this vocabulary enforced? An enforced vocabulary requires that the user input for this field match one of the vocabulary items specified in the 'vocabularies' array. |
| duplicates | Boolean true/false. Can more that one copy of this attribute exist? If true, then there can be multiple entries for the attribute. If false, there can only be one. (e.g. Library of Congress allows multiple subjects for books, iTunes Podcasts allow multiple categories) |
| required | Boolean true/false. Must this field be populated? If true, an error will result if metadata is submitted but this field is blank. |
GET Method: List vocabularies for specified attribute
/api/metadata/[profile_id]/attributes/[attribute_id]/vocabualry/
Request — This call will retrieve any vocabularies associated with a specified profile attribute. Must be authenticated as an admin.
| Attribute | Description |
|---|---|
| profile_id (required) | The id of the metadata profile you are querying. Put this in the URL, as above, this is given when you create the profile. |
| attribute_id (required) | The id of the metadata profile attribute you are querying. Put this in the URL, as above, this is given when you create the profile. |
Response — An array listing the following attributes for each item within the vocabulary
| Attribute | Description |
|---|---|
| vocabulary_id | Unique identifier used by Warpwire to track the vocabulary element. This will be a positive interger. |
| data | User-readbale vocabulary term. |
| active | Boolean true/false. If 'True,' the vocabulary term will display in the user interface. |
GET Method: Get information about specific vocabulary item for specified attribute in specified profile.
/api/metadata/[profile_id]/attributes/[attribute_id]/vocabulary/[vocabulary_id]/
Request — This call will return information on the specified vocabulary term You must be authenticated, though you do not need to be an admin user.
| Attribute | Description |
|---|---|
| profile_id (required) | The id of the metadata profile you are querying. Put this in the URL, as above. This value is given when you create the profile. |
| attribute_id (required) | The id of the metadata profile attribute you are querying. Put this in the URL, as above. This value is given when you create the profile sttribute. |
| vocabulary_id (required) | The id of the vocabulary item you are querying. Put this in the URL, as above. This value is given when you create the vocabulary item. |
Response — An array listing the following attributes for each item within the vocabulary
| Attribute | Description |
|---|---|
| vocabulary_id | Unique identifier used by Warpwire to track the vocabulary element. This will be a positive interger. |
| data | User-readbale vocabulary term. |
| active | Boolean true/false. If 'True,' the vocabulary term will display in the user interface. |
POST Method: Add vocabulary term to profile attribute
/api/metadata/[profile_id]/attributes/[attribute_id]/vocabulary/
Request — This call will add a vocabulary term to the specified attribute within a specified profile. You must be authenticated, though you do not need to be an admin user.
| Attribute | Description |
|---|---|
| profile_id (required) | The id of the metadata profile you are querying. Put this in the URL, as above, this is given when you create the profile. |
| attribute_id (required) | The id of the metadata profile attribute you are querying. Put this in the URL, as above, this is given when you create the profile. |
| data (required) | The vocabulary term you are adding to the attribute. |
| active | Boolean true/false. If 'True,' the vocabulary term will display in the user interface. |
Response — This POST request will return: Status 201: Created, along with an array showing the id, data, and active values you just specified.
PUT Method: Modify existing vocabulary term within a specific profile attribute.
/api/metadata/[profile_id]/attributes/[attribute_id]/vocabulary/[vocabulary_id]
Request — This call will update a vocabulary term to the specified attribute within a specified profile. You must be authenticated as an admin user.
| Attribute | Description |
|---|---|
| profile_id (required) | The id of the metadata profile you are querying. Put this in the URL, as above, this is given when you create the profile. |
| attribute_id (required) | The id of the metadata profile attribute you are querying. Put this in the URL, as above, this is given when you create the profile. |
| vocabulary_id | The id of the vocabulary term for the metadata profile attribute you specified. Put this in the URL, as above, this is given when you create the vocabulary item originally. |
| data (required) | The vocabulary term you are adding to the attribute. |
Response — This PUT request will return: Status 202: Modified, along with an array showing the id, data, and active values you just specified.
The membership API call returns information regarding group membership. The membership API call requires authentication.
GET Method:
/api/membership/u/[Warpwire_Unique_ID]/
Request — This will retrieve a list of groups associated with the user whose unique ID is provided.
| Attribute | Description |
|---|---|
| Warpwire_Unique_ID (required) | If you do not already know the Warpwire Unique ID associated with a given user, you can get the Warpwire Unique ID by querying the user with the /api/group/q/[QUERY]/ call (with type set to 'user'). The objectId in the call response is the value you will use for this membership query. |
Response — For any GET request the following information can be returned. This call will return an array of objects that contain the properties specified below, or the empty set.
| Attribute | Description |
|---|---|
| id | The identifier associated with the user. This is Warpwire's internal unique reference. |
| unique_id | The unique identifier used by your organization to identify the user. |
| creation | The creation date of the user. |
| first_name | The first name of the user. |
| last_name | The last name of the user. |
| groups | An array containing all the groups associated with the Warpwire Unique ID. |
GET Method:
/api/membership/g/[Warpwire_Group_ID]/
Request — This will retrieve a list of users associated with the group whose unique ID is provided.
| Attribute | Description |
|---|---|
| Warpwire_Group_ID (required) | If you do not already know the Warpwire Group ID associated with a given group, you can get the Warpwire Group ID by querying the group with the /api/group/q/[QUERY]/ call (with type set to 'group'). The objectId in the call response is the value you will use for this membership query. |
Response — For any GET request the following information can be returned. This call will return an array of objects that contain the properties specified below, or the empty set.
| Attribute | Description |
|---|---|
| id | The identifier associated with the group. This is Warpwire's internal unique reference. |
| unique_id | The unique identifier used by your organization to identify the group. |
| creation | The creation date of the group. |
| name | The name of the group. |
| users | An array containing all the users associated with the Warpwire Group ID. |
POST Method:
/api/membership/
Request — This will add a user to a group, based on provided IDs.
| Attribute | Description |
|---|---|
| user_id (required) | The id associated with the user who is being added to the group. |
| group_id (required) | The id associated with the group who is having a user. |
Response — For POST requests a HTTP 201 status code is returned. There is no other information provided in the response.
DELETE Method:
/api/membership/
Request — This will delete a user from a group, based on provided IDs.
| Attribute | Description |
|---|---|
| user_id (required) | The id associated with the user who is being removed from the group. |
| group_id (required) | The id associated with the group who is having a user removed from it. |
Response — For DELETE requests a HTTP 204 status code is returned. There is no other information provided in the response.
The permission API call returns information regarding access control levels. The permission API call requires authentication.
GET Method:
/api/permission/c/[collection_uuid]/o/[user_id]/
Request — For any GET request the following information must be provided.
| Attribute | Description |
|---|---|
| collection_uuid (required) | A valid collection UUID resource. |
| user_id (required) | A valid user identifier. If this value is 0, it will return user information for the entire collection. |
Response — For any GET request the following information can be returned. This call will return an array of objects that contain the properties specified below, or the empty set.
| Attribute | Description |
|---|---|
| firstName | The requested user’s first name. |
| lastName | The requested user’s last name. |
| userId | The requested user’s identifier. |
| uniqueId | The requested user's SSO unique identifier. |
PUT Method:
/api/permission/c/[collection_uuid]/o/[user_id]/
Request — Adds a user to a collection. Any parameter not specified in the URL above must be submitted as a PUT data field. For any PUT request the following information can be provided.
| Attribute | Description |
|---|---|
| collection_uuid (required) | A valid collection UUID resource. |
| user_id (conditional) | The requested user’s identifier. If this value is 0, the uniqueId PUT data field is required. |
| uniqueId (conditional) | The requested user's SSO unique identifier. Required if the user_id is 0. |
| level | The permission level to assign to the user. Possible values are "none", "view", or "admin". Default value is "view". |
Response — For PUT requests a HTTP 201 status code is returned. There is no other information provided in the response.
POST Method:
Identical to the PUT Method. See above.
DELETE Method:
/api/permission/c/[collection_uuid]/o/[user_id]/
Request — Removes a user from a collection. For any DELETE request the following information must be provided.
| Attribute | Description |
|---|---|
| collection_uuid (required) | A valid collection UUID resource. |
| user_id (required) | A valid user identifier. |
Response — For DELETE requests a HTTP 200 status code is returned. There is no other information provided in the response.
The info API call returns information for objects. The info API call requires authentication.
GET Method:
/api/info/c/[collection_uuid]/o/[object_id]/
Request — For any GET request the following information must be provided.
| Attribute | Description |
|---|---|
| collection_uuid (required) | A valid collection UUID resource. |
| object_id (required) | A valid object UUID resource. |
Response — For any GET request the following information can be returned.
| Attribute | Description |
|---|---|
| type | A textual version of the type of resource. This value will be "info". |
| owner | An array containing information about the owner of the object. |
| owner.userId | The object owner’s user identifier. |
| owner.firstName | The object owner’s first name. |
| owner.lastName | The object owner’s last name. |
| title | The title of the resource. A title may be blank or can be up to 255 characters in length. |
| description | The description of the object. The description may be blank. |
| created | An Epoch timestamp of the date the object was created. |
| modified | An Epoch timestamp of the date the object was modified. |
| properties | An array of properties that accompany the object. This could be an empty set. |
| uuid | The universally unique identifier of the object. |
| fileType | A textual version of the type of file. This could include "catalog", "video", "audio", "file", etc. |
| duration | The duration of the media object in seconds. |
POST Method:
/api/info/c/[collection_uuid]/o/[user_id]/
Request — For any GET request the following information must be provided.
| Attribute | Description |
|---|---|
| collection_uuid (required) | A valid collection UUID resource. |
| object_id (required) | A valid object UUID resource. |
| title | The title of the object. A title may be blank or can be up to 255 characters in length. |
| description | The description of the object. The description may be blank. |
Response — For POST requests a HTTP 202 status code is returned. There is no other information provided in the response.
The embed API call returns information regarding embedding an object. The embed API call requires authentication.
GET Method:
/api/embed/c/[collection_uuid]/o/[object_id]/
Request — For any GET request the following information must be provided.
| Attribute | Description |
|---|---|
| collection_uuid (required) | A valid collection UUID resource. |
| object_id (required) | A valid object UUID resource. |
Response — For any GET request the following information can be returned.
| Attribute | Description |
|---|---|
| type | A textual version of the type of resource. This value will be "embed". |
| properties | An array of properties that accompany the object. This could be an empty set. |
| properties.link | URL of object. |
| properties.iframe | Iframe embed code for the object. |
| properties.script | JavaScript embed code for the object. |
The video API call returns information about a video object. The video API call requires authentication.
GET Method:
/api/video/c/[collection_uuid]/o/[object_id]/
Request — For any GET request the following information must be provided.
| Attribute | Description |
|---|---|
| collection_uuid (required) | A valid collection UUID resource. |
| object_id (required) | A valid object UUID resource. |
Response — For any GET request the following information can be returned.
| Attribute | Description |
|---|---|
| type | A textual version of the type of resource. This value will be "video". |
| duration | The duration in seconds of the asset (if applicable) represented as a positive interger. |
| files | An array with information about each version of the video file. The files array contains the following five items: |
| files.format | The format of the video file. This can include "hls", "smil", or "mp4". |
| files.url | The URL of the video file. |
| files.label | The quality label for the video file, as displayed in the UI (e.g. 360p.) |
| files.bitrate | The video file's bitrate. |
| files.properties | An array of properties for the video file. Please note that the properties array may be an empty set. The array contains the following two items: |
| files.properties.thumbnail | The thumbnail image for the Web Video Text Tracks (VTT) file for the video. |
| files.properties.captions | An array with links to all attaches caption files for the video, as key value pairs of the caption language and the direct link to the caption file. |
| images | An array of images that accompany the object. Please note that the images array may be an empty set. The images array may contain the following items: |
| images.thumbnail | A 128x128 pixel image of the resource (if available). |
| images.square | A 512x512 pixel image of the resource (if available). |
| images.large | A 1280x760 pixel image of the resource (if available). |
| properties | An array of files that accompany the object. Please note that the files array may be an empty set. |
| uuid | The universally unique identifier of the object. |
The authenticate API call returns information regarding authentication of users. The authenticate API call does not require authentication.
GET Method:
/api/authenticate/
Request — For any GET request no further information needs to be provided.
Response — For any GET request the following information is returned.
| Attribute | Description |
|---|---|
| type | A textual version of the type of resource. This value will be "authenticate". |
| authenticated | Is the current user authenticated? The values can include either "true" or "false". If you do not provide an authenticated user, the result will always be "false". |
The catalog API call returns information regarding all objects that exists within a collection. The catalog API call requires authentication.
GET Method:
/api/catalog/c/[collection_uuid]/o/[object_uuid]/
Request — For any GET request the following information must be provided.
| Attribute | Description |
|---|---|
| collection_uuid (required) | A valid collection UUID resource. |
| object_uuid (required) | A valid object UUID resource. |
| ts | The Epoch timestamp. If provided, only objects that have been updated since the timestamp will be returned. Cannot be 0. |
| completeRecords | The number of complete records to return. If not provided, all returned objects will be complete describe objects. |
Response — For any GET request the following information is returned. This call will return an array of objects that contain the properties specified below, or the empty set.
| Attribute | Description |
|---|---|
| ts | The Epoch timestamp at which the request occurred. |
| list | An array of objects which exhibit the properties below, or the empty set. |
| type | A textual version of the type of resource. This could include "catalog", "video", "audio", "file", etc. |
| title | The title of the resource. A title may be blank or can be up to 255 characters in length. |
| images | An array of images that accompany the object. Please note that the images array may be an empty set. |
| images.thumbnail | A 128x128 pixel image of the resource (if available). |
| images.square | A 512x512 pixel image of the resource (if available). |
| images.large | A 1280x760 pixel image of the resource (if available). | description | Textual description of the object. This may be blank. |
| properties | An array of properties that accompany the object. This could be an empty set. |
| uuid | The universally unique identifier of the object. |
| userId | Identifier of user who created the resource. This information is not informative without performing an additional user API call. |
| authenticated | Indicates if the current user is authenticated. Value is either "true" or "false". |
| created | An Epoch timestamp of the date the object was created. |
| modified | An Epoch timestamp of the date the object was modified. |
PUT Method:
/api/catalog/c/[collection_uuid]/o/[object_uuid]/
Request — Adds an object to a collection. Any parameter not specified in the URL above must be submitted as a PUT data field. For any PUT request the following information can be provided.
| Attribute | Description |
|---|---|
| collection_uuid (required) | A valid collection UUID resource. |
| object_uuid (required) | A valid collection or object UUID resource. |
Response — For PUT requests a HTTP 201 status code is returned. There is no other information provided in the response.
POST Method:
Identical to the PUT Method. See above.
DELETE Method:
/api/catalog/c/[collection_uuid]/o/[object_uuid]/
Request — Removes an object from a collection. For any DELETE request the following information must be provided.
| Attribute | Description |
|---|---|
| collection_uuid (required) | A valid collection UUID resource. |
| object_uuid (required) | A valid collection or object UUID resource. |
Response — For DELETE requests a HTTP 200 status code is returned. There is no other information provided in the response.
The contribute API call returns information regarding group membership of an object. The contribute API call requires authentication.
GET Method:
/api/contribute/o/[object_id]/
Request — For any GET request the following information must be provided.
| Attribute | Description |
|---|---|
| object_id (required) | A valid object UUID resource. |
Response — For any GET request an array of the following information can be returned.
| Attribute | Description |
|---|---|
| uuid | The universally unique identifier of the media library. |
| title | The title of the resource. A title may be blank or can be up to 255 characters in length. |
| member | Whether or not the object is a member of the corresponding media library. |
The oauth API allows for providers of the external services to interact with the Warpwire OAuth service to invoke an OAuth2 request, whitelist domains, and update configuration information. A more detailed view of the OAuth2 authentication workflow. The following OAuth API calls require using HTTP Basic Authorization using the Oauth2 client key as the username and the client secret as the password.
GET Method:
/api/oauth/whitelist/
Authorization — HTTP basic authorization.
Response — For any GET request the following information can be returned in a JSON formatted object.
| list | An array of whitelisted domains that are approved for use with the Oauth2 provider. |
| list[x].id | A unique identifier for the whitelist parameters. This id must be used for subsequent oauth API calls. |
| list[x].url | The target URL for the whitelisted domain. If there are no restrictions to the domains that the provider may target, this value will read "Unrestricted." |
| list[x].created | The date and time the whitelist URL was created in ISO-8601 format. |
| count | The number of whitelisted domains available to the provider |
POST Method:
/api/oauth/whitelist/
Authorization — HTTP basic authorization.
Request — Creates a new whitelist domain for the Oauth2 provider. The provided whitelist domain must be a valid URI and cannot be a duplicate whitelist domain for the same provider.
| Attribute | Description |
|---|---|
| url | Whitelist domain for OAuth2 requests to be returned to the provider for further processing. |
Response — A successful POST request will return a HTTP 201 response code along with a JSON object confirming the successful creation of the object.
| Attribute | Description |
|---|---|
| status | The status of the POST request. In most cases this value will return "success." |
PUT Method:
/api/oauth/whitelist/
Authorization — HTTP basic authorization.
Request — Updates an existing whitelist domain for the Oauth2 provider. The unique identifier for the existing whitelist domain is required, see GET request above. Additionally, the provided whitelist domain must be a valid URI and cannot be a duplicate whitelist domain for the same provider.
| Attribute | Description |
|---|---|
| id | The unique identifier for the whitelist domain for the provider. This information may be retrieved by using the whitelist GET API call. |
| url | Whitelist domain for OAuth2 requests to be returned to the provider for further processing. |
Response — A successful PUT request will return a HTTP 202 response code along with a JSON object confirming the successful creation of the object.
| Attribute | Description |
|---|---|
| status | The status of the PUT request. In most cases this value will return "success." |
DELETE Method:
/api/oauth/whitelist/
Authorization — HTTP basic authorization.
Request — Removes an existing whitelist domain for the Oauth2 provider. The unique identifier for the existing whitelist domain is required, see GET request above. You may not remove the final domain for a provider, this will result in an error response.
| Attribute | Description |
|---|---|
| id | The unique identifier for the whitelist domain for the provider. This information may be retrieved by using the whitelist GET API call. |
Response — A successful DELETE request will return a HTTP 200 response code along with a JSON object confirming the successful creation of the object.
| Attribute | Description |
|---|---|
| status | The status of the DELETE request. In most cases this value will return "success." |
The oembed API provides an easy way for you to place certain kinds of media content, including Warpwire videos, on external websites. By accessing a special URL that corresponds to the content that you want to embed, you get detailed information about this content, including an embeddable iframe element.
Please note: The OEmbed standard is separate from the Warpwire API, so you don't need API authentication to use this functionality.
You will need the URL of a video on Warpwire. If you are unsure about where to find the share URL, please visit our Support Guide.
GET Request:
Get an oEmbed response for a video — To get an oEmbed response for a video on Warpwire, send a GET request to the following URL:
https://example.warpwire.com/api/oauth/?url=LINK_URL
NOTE: Be sure to URL encode the LINK_URL value:
https://example.warpwire.com/api/oembed/?url=https%3A%2F%2Fexample.warpwire.com%2Fw%2FAAAAAA%2F&width=480&height=360&format=json
Table 1. URL schemas
| The video is... | URL scheme |
|---|---|
| A regular Warpwire video | https://example.warpwire.com/w/{video_id}/ |
Make sure that all parameters are URL encoded. We provide a default width and height settings for all assets, but if you'd like to provide you own default sizes you can use the URL examples below:
GET https://example.warpwire.com/api/oembed/?url=https%3A%2F%2Fexample.warpwire.com%2Fw%2FAAAAAA%2F&width=480&height=360
GET https://example.warpwire.com/api/oembed/?url={video_url}&format=json
Table 2. oEmbed arguments
| Argument | Description |
|---|---|
| autoplay | Whether to start playback of the video automatically. This feature might not work on all devices. Default value is "false". |
| cc_enabled | You can turn caption on by default. When activated the available caption file will be played. In the case that there are multiple caption available, the player will default to “English”. Default value is "false". |
| controls | Whether to display (true) or hide (false) all interactive elements in the player interface. To start video playback when controls are hidden, set autoplay to true or use our Player API. Default value is "true". |
| height | The height of the video in pixels. |
| muted | Whether to mute playback by default. The user can increase the volume manually. Default value is "false". |
| share | Controls showing the share link on the video so that users can share the link with others. Default value is "true". |
| title | Whether to display the video's title. Default value is "true". |
| thumbnail_height | The height of the thumbnail images for the asset. |
| thumbnail_width | The width of the thumbnail image for the asset. |
| transcript | Show an interactive transcript that plays along with the video if a caption is present. |
| width | The width of the video in pixels. |
| url | The URL of the video on Warpwire. This is a required value. |
Under normal circumstances, the response contains various pieces of metadata in JSON format, including the video's embeddable iframe element in the html field.
{
"version": "1.0",
"provider_url": "https://example.warpwire.com",
"provider_name": "Warpwire",
"is_public": true,
"duration": 50.25,
"has_caption": true,
"links": {
"caption": [
{
"label": "English",
"url": "https://example.warpwire.com/api/caption/AwAAAA/1/vtt/"
}
]
},
"views": 1,
"upload_date": "2020-01-01T00:00:00+00:00",
"description": "An example description",
"author_name": "Jane Smith",
"html": "< iframe width=\"640\" height=\"360\" src=\"https://example.warpwire.com/w/AwAAAA/?audio_only=1&autoplay=1&controls=1\" frameborder=\"0\" allow=\"autoplay; encrypted-media; camera; microphone; picture-in-picture\" allowfullscreen>iframe">,
"height": 360,
"width": 640,
"thumbnail_height": 360,
"thumbnail_width": 640,
"url": "https://example.warpwire.com/w/AwAAAA/?audio_only=1&autoplay=1&controls=1",
"type": "video",
"title": "An example file",
"thumbnail_url": "https://example.warpwire.com/image/large/"
}
NOTE: If you want a response in XML instead of in JSON, substitute format=xml for format=json in the URL.
See Table 3 for descriptions of these fields.
Table 3. oEmbed response fields
| Field | Description |
|---|---|
| author_name | The owner of the video. |
| description | The description of the video. |
| duration | The duration of the video in seconds. |
| has_captions | (Optional) A Boolean to indicate if the video contains closed captions. |
| height | The height of the video in pixels. |
| is_public | The video is available to the public to watch. |
| links.captions | (Optional) Contains one or more entries including the label and URL for the corresponding caption file for the video. It follows the format: entry.label and entry.url. |
| html | The iframe element for embedding the video. |
| provider_name | The name of the oEmbed provider, which in this case is Warpwire. |
| provider_url | The URL of the oEmbed provider, which in this case is https://warpwire.com/. |
| thumbnail_height | The URL of the video's thumbnail image. |
| thumbnail_url | The URL of the video's thumbnail image. |
| thumbnail_width | The width of the video's thumbnail image. |
| title | The title of the video. |
| type | The type of the oEmbed, which in this case is video. |
| upload_date | The date and time when the video was uploaded. |
| url | The URL of the video. |
| views | (Optional) Number of views of the video. |
| version | The version of the oEmbed spec. |
| width | The width of the video in pixels. |
Note: If your video is not public you may receive a slightly different response.
Embed the video
To embed the video, take the unescaped value of the html field, and include it in your HTML page.
<html>
<head>
<title>{page_title}</title>
</head>
<body>
<iframe src=“https://example.warpwire.com/w/{video_id}/” width="{video_width}" height="{video_height}" frameborder="0" title="{video_title}" webkitallowfullscreen mozallowfullscreen allowfullscreen>iframe>
</body>
</html>
Discovering the oEmbed URL
Under normal circumstances, the
head section of a video's page on Warpwire includes two link elements: one with type application/json+oembed, and the other with type text/xml+oembed.
<link rel="alternate" type="application/json+oembed" href=“https://example.warpwire.com/api/oembed/?url=https%3A%2F%2Fexample.warpwire.com%2Fw%2FAwAAAA%2F&format=json” title="Warpwire Video">
In these links, the href attribute contains the URL for obtaining the oEmbed response in either JSON or XML format, depending on which one you use. These elements enable you to copy your video's URL and use it anywhere that oEmbed is supported.
Handling errors
Whenever oEmbed isn't working properly and you're sure that the video URL is correct, check the HTTP status code that you get back, and refer to Table 4.
| HTTP status code | Probable cause |
|---|---|
| 403 | Embed permissions are disabled for this video, so you can't embed it. |
| 404 | You aren't able to access the video because of privacy or permissions issues, or because the video is still transcoding. |
All calls to the REST API will always return a standard HTTP 1.1 status code as a response. The status codes that the Warpwire API will return are listed below.
| Status Code | Description |
|---|---|
| 200 | OK. The request is successful. |
| 201 | Created. The resource has been successfully created. |
| 202 | Accepted. The resource has been successfully modified. |
| 302 | Temporarily redirected. The resource has moved and you will need to follow the URL for the updated resource. |
| 400 | Bad Request. The API call could not be processed because one or more input parameters are not valid. Please confirm all parameters are correct. |
| 401 | Unauthorized. The user needs to authenticate to view a resource. Please direct the user to the authentication endpoint. |
| 403 | Forbidden. The user does not have access to the requested resource. They must be added to the appropriate collection or group. |
| 404 | Not Found. The resource could not be located or the API method could not be found. |
| 409 | Conflict. There is a conflict that prevents an object from being updated or created. The error message should contain additional information. |
| 500 | Internal Server Error. These errors are not generated by the API directly and indicate an issue with the server. Please contact Warpwire for an appropriate resolution. |
| 501 | Not Implemented. You are requesting an API call that has not yet been implemented. Please use a different method. |
| 503 | Service Unavailable. The Warpwire servers are currently unavailable to fulfill your request. Please wait a few moments and try your request again. |
