Adways APIs documentation

Media

A "Media" can be assimilated as a "resource" or an "asset", but not as a "file". It is an abstraction of the "file" concept. It is useful to group multiple files under one same and unique entity. In the Adways environment, the "Media" API works closely with the "MediaElement" API, whose entities stand for "files". As an example, one unique video can be encoded in multiple formats (bitrates, sizes, etc.); the video is added into the "Media" API, whereas all of the generated streams are added into the "MediaElement" API. A Media Entity has at least 1 Media Element Entity.

Fields

Field	Description	Required
name	The media name.	YES
mime	The mime type (ex.: video/x-youtube).	YES
xkey	An identifier understood by the associated player, in case of custom mime type such as 'video/x-youtube'.	NO
path	A URL to the media.	NO
thumbnails	Serialized array of 'MediaElement'.	NO
assets	Serialized array of 'MediaElement'.	NO
state	Entity's state.	NO

GET /media

Loads a collection of available entities. The loaded collection is paginated. An optional "search" parameter is available to filter the result on the entities' name and id (ex.: "//media?search=SearchValue").

Request

EndPoint

https://services.adways.com/media

Headers

Header	Value
Accept	application/vnd.media.v1+json application/hal+json application/json

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.media.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{
    "_links": {
        "self": {
            "href": "/media"
        },
        "first": {
            "href": "/media?page={page}"
        },
        "prev": {
            "href": "/media?page={page}"
        },
        "next": {
            "href": "/media?page={page}"
        },
        "last": {
            "href": "/media?page={page}"
        }
    },
    "_embedded": {
        "collection": [
            {
                "id": "",
                "created": "",
                "author": "",
                "updated": "",
                "updator": "",
                "level": "",
                "state": "Entity's state.",
                "name": "The media name.",
                "mime": "The mime type (ex.: video/x-youtube).",
                "xkey": "An identifier understood by the associated player, in case of custom mime type such as 'video/x-youtube'.",
                "path": "A URL to the media.",
                "thumbnails": "Serialized array of 'MediaElement'.",
                "assets": "Serialized array of 'MediaElement'.",
                "_links": {
                    "self": {
                        "href": "/media[/:media_id]"
                    }
                }
            }
        ]
    }
}

POST /media

Creates an entity in Media. Required fields are in the API fields description above. Note that on success, the returned http status is "201, Created".

Request

EndPoint

https://services.adways.com/media

Headers

Header	Value
Accept	application/vnd.media.v1+json application/hal+json application/json
Content-Type	application/vnd.media.v1+json application/json

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
201: Created
400: Client Error
422: Unprocessable Entity
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.media.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{
    "id": "",
    "created": "",
    "author": "",
    "updated": "",
    "updator": "",
    "level": "",
    "state": "Entity's state.",
    "name": "The media name.",
    "mime": "The mime type (ex.: video/x-youtube).",
    "xkey": "An identifier understood by the associated player, in case of custom mime type such as 'video/x-youtube'.",
    "path": "A URL to the media.",
    "thumbnails": "Serialized array of 'MediaElement'.",
    "assets": "Serialized array of 'MediaElement'.",
    "_links": {
        "self": {
            "href": "/media[/:media_id]"
        }
    }
}

GET /media[/:media_id]

Loads the entity with the given id.

Request

EndPoint

https://services.adways.com/media[/:media_id]

Headers

Header	Value
Accept	application/vnd.media.v1+json application/hal+json application/json

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
404: Not Found
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.media.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{
    "id": "",
    "created": "",
    "author": "",
    "updated": "",
    "updator": "",
    "level": "",
    "state": "Entity's state.",
    "name": "The media name.",
    "mime": "The mime type (ex.: video/x-youtube).",
    "xkey": "An identifier understood by the associated player, in case of custom mime type such as 'video/x-youtube'.",
    "path": "A URL to the media.",
    "thumbnails": "Serialized array of 'MediaElement'.",
    "assets": "Serialized array of 'MediaElement'.",
    "_links": {
        "self": {
            "href": "/media[/:media_id]"
        }
    }
}

PATCH /media[/:media_id]

Updates a subset of the entity with the given id (only the modified fields are required).

Request

EndPoint

https://services.adways.com/media[/:media_id]

Headers

Header	Value
Accept	application/vnd.media.v1+json application/hal+json application/json
Content-Type	application/vnd.media.v1+json application/json

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
404: Not Found
400: Client Error
422: Unprocessable Entity
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.media.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{
    "id": "",
    "created": "",
    "author": "",
    "updated": "",
    "updator": "",
    "level": "",
    "state": "Entity's state.",
    "name": "The media name.",
    "mime": "The mime type (ex.: video/x-youtube).",
    "xkey": "An identifier understood by the associated player, in case of custom mime type such as 'video/x-youtube'.",
    "path": "A URL to the media.",
    "thumbnails": "Serialized array of 'MediaElement'.",
    "assets": "Serialized array of 'MediaElement'.",
    "_links": {
        "self": {
            "href": "/media[/:media_id]"
        }
    }
}

PUT /media[/:media_id]

Updates the entire entity with the given id (all the fields are required).

Request

EndPoint

https://services.adways.com/media[/:media_id]

Headers

Header	Value
Accept	application/vnd.media.v1+json application/hal+json application/json
Content-Type	application/vnd.media.v1+json application/json

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
404: Not Found
400: Client Error
422: Unprocessable Entity
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.media.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{
    "id": "",
    "created": "",
    "author": "",
    "updated": "",
    "updator": "",
    "level": "",
    "state": "Entity's state.",
    "name": "The media name.",
    "mime": "The mime type (ex.: video/x-youtube).",
    "xkey": "An identifier understood by the associated player, in case of custom mime type such as 'video/x-youtube'.",
    "path": "A URL to the media.",
    "thumbnails": "Serialized array of 'MediaElement'.",
    "assets": "Serialized array of 'MediaElement'.",
    "_links": {
        "self": {
            "href": "/media[/:media_id]"
        }
    }
}

DELETE /media[/:media_id]

Deletes the entity with the given id. Note that on success, the returned http status is "204, Entity has been deleted".

Request

EndPoint

https://services.adways.com/media[/:media_id]

Headers

Header	Value
Accept	application/vnd.media.v1+json application/hal+json application/json

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
204: No Content
404: Not Found
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.media.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

CreateMediaFromYoutubeUrl

This RPC helps adding a new Youtube media into the "Media" API. It accepts a full Youtube URL or a simple Youtube video's identifier (the "xkey" "Media" API field); it automatically retrieves the thumbnails and creates the corresponding "MediaElement".

Fields

Field	Description	Required
youtube_media	Youtube video id or Youtube video URL	YES

POST /create-media-from-youtube

youtube_media can be a Youtube video URL of just a Youtube video key.

Request

EndPoint

https://services.adways.com/create-media-from-youtube

Headers

Header	Value
Accept	application/vnd.media.v1+json application/json application/*+json
Content-Type	application/vnd.media.v1+json application/json

Body

{
   "youtube_media": ""
}

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
201: Created
404: Not Found
400: Client Error
422: Unprocessable Entity
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.media.v1+json application/json application/*+json
Allow	Comma-separated list of all HTTP methods allowed

Body

{
    "id": "",
    "created": "",
    "author": "",
    "updated": "",
    "updator": "",
    "level": "",
    "state": "",
    "name": "the media name",
    "mime": "video/x-youtube",
    "xkey": "Youtube video id",
    "path": "full URL",
    "thumbnails": "Serialized array of MediaElement",
    "assets": "Serialized array of MediaElement"
}

Home / Documentation

Media (v1)

Media

Fields

GET /media

Request

EndPoint

Headers

Response

Status Codes

Headers

Body

POST /media

Request

EndPoint

Headers

Response

Status Codes

Headers

Body

GET /media[/:media_id]

Request

EndPoint

Headers

Response

Status Codes

Headers

Body

PATCH /media[/:media_id]

Request

EndPoint

Headers

Response

Status Codes

Headers

Body

PUT /media[/:media_id]

Request

EndPoint

Headers

Response

Status Codes

Headers

Body

DELETE /media[/:media_id]

Request

EndPoint

Headers

Response

Status Codes

Headers

CreateMediaFromYoutubeUrl

Fields

POST /create-media-from-youtube

Request

EndPoint

Headers

Body

Response

Status Codes

Headers

Body