RESTful API of Media Files Bounded Context

Headers

As API is working with JSON every request must add the following headers:

Accept: application/json

And for request with body:

Content-Type: application/json

In order to use this API we must authenticate using the user&identity bounded context, and the token must be set in the request header:

Authorization: aa.bb.cc

User Impersonation

It is possible for an admin user (role mediafiles_admin) to make requests on behalf of other users. The request is processed as if the impersonated user did the request himself.

The following headers must be added in order to impersonate a user with the desired roles:

X-Impersonated-User-Id: johndoe@spotahome.com
X-Impersonated-User-Roles: mediafiles_uploader

The X-Impersonated-User-Roles accepts a comma-separated list of roles for the impersonated user.

Albums ¶

Creation of a new album
POST`/albums`

Example URI

POST /albums

Request

HideShow

Headers

Content-Type: application/json
Authorization: aa.bb.cc

Body

{
  "title": "Gardening videos",
  "categoryId": "listingsMadrid",
  "reference": "90942"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "categoryId": {
      "type": "string"
    },
    "reference": {
      "type": "string"
    }
  },
  "required": [
    "title",
    "categoryId"
  ]
}

Response 201

HideShow

Headers

Location: /albums/8f2dbe69-b68f-4423-bc93-b8b036727a032

Retrieve albums by criteria
GET`/albums{?categoryId}{?reference}{?page}{?itemsPerPage}`

Example URI

GET /albums?categoryId=listingsMadrid?reference=90987?page=1?itemsPerPage=10

URI Parameters

HideShow

categoryId: string (optional) Example: listingsMadrid
reference: string (optional) Example: 90987
page: number (optional) Example: 1
itemsPerPage: number (optional) Example: 10

Request

HideShow

Headers

Content-Type: application/json
Authorization: aa.bb.cc

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    "count": 1,
    "total": 28,
    "_links": {
        "self": {
            "href": "/albums?itemsPerPage=1&page=1"
        },
        "first": {
            "href": "/albums?itemsPerPage=1&page=1"
        },
        "last": {
            "href": "/albums?itemsPerPage=1&page=28"
        },
        "next": {
            "href": "/albums?itemsPerPage=1&page=2"
        }
    },
    "_embedded": {
        "albums": [
            {
                "_id": "853d5ee1-dbec-4015-843c-cb55943a1c7b",
                "title": "Gardening videos",
                "categoryId": "listingsBarcelona",
                "reference": "90876",
                "status": "complete",
                "videoIds": [
                    "653d5ee1-dbec-4015-843c-cb55943a1c7c",
                    "153d5ee1-dbec-4015-843c-cb55943a1c7d",
                    "953d5ee1-dbec-4015-843c-cb55943a1c7e",
                    "f53d5ee1-dbec-4015-843c-cb55943a1c7f"
                ],
                "photoIds": [],
                "video360Ids": [],
                "photo360Ids": [],
                "creationUser": "maikel@spotahome.com",
                "updateUser": "hugo@spotahome.com",
                "creationDate": "2017-01-03T09:00:00+01:00",
                "updateDate": "2017-01-03T09:00:00+01:00"
            },
            {
                "_id": "38ef38ab-352d-3561-5976-cb55943a1c7b",
                "title": "Gardening videos 2",
                "categoryId": "listingsBarcelona",
                "reference": "90877",
                "status": "complete",
                "videoIds": [
                    "653d5ee1-dbec-4015-843c-cb55943a1c7c",
                    "153d5ee1-dbec-4015-843c-cb55943a1c7d",
                    "953d5ee1-dbec-4015-843c-cb55943a1c7e",
                    "f53d5ee1-dbec-4015-843c-cb55943a1c7f"
                ],
                "photoIds": [],
                "video360Ids": [],
                "photo360Ids": [],
                "creationUser": "maikel@spotahome.com",
                "updateUser": "hugo@spotahome.com",
                "creationDate": "2017-01-03T09:00:00+01:00",
                "updateDate": "2017-01-03T09:00:00+01:00"
            }
        ]
}

Album with an ID ¶

Fetch single album
GET`/albums/{id}`

Example URI

GET /albums/853d5ee1-dbec-4015-843c-cb55943a1c7b

URI Parameters

HideShow

id: string (required) Example: 853d5ee1-dbec-4015-843c-cb55943a1c7b
Id of an album.

Request

HideShow

Headers

Content-Type: application/json
Authorization: aa.bb.cc

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "_id": "853d5ee1-dbec-4015-843c-cb55943a1c7b",
  "title": "Gardening videos",
  "categoryId": "listingsMadrid",
  "reference": "90876",
  "status": "draft",
  "videoIds": [
    "653d5ee1-dbec-4015-843c-cb55943a1c7c",
    "153d5ee1-dbec-4015-843c-cb55943a1c7d",
    "953d5ee1-dbec-4015-843c-cb55943a1c7e",
    "f53d5ee1-dbec-4015-843c-cb55943a1c7f"
  ],
  "photoIds": [],
  "video360Ids": [],
  "photo360Ids": [],
  "creationUser": "maikel@spotahome.com",
  "updateUser": "hugo@spotahome.com",
  "creationDate": "2017-01-03T09:00:00+01:00",
  "updateDate": "2017-01-03T09:00:00+01:00"
}

Update single album
PUT`/albums/{id}`

Example URI

PUT /albums/853d5ee1-dbec-4015-843c-cb55943a1c7b

URI Parameters

HideShow

id: string (required) Example: 853d5ee1-dbec-4015-843c-cb55943a1c7b
Id of an album.

Request

HideShow

Headers

Content-Type: application/json
Authorization: aa.bb.cc

Body

{
  "title": "Gardening videos",
  "reference": "90942"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "reference": {
      "type": "string"
    }
  }
}

Response 204

HideShow

Headers

Content-Type: application/json

Delete single album
DELETE`/albums/{id}`

Example URI

DELETE /albums/853d5ee1-dbec-4015-843c-cb55943a1c7b

URI Parameters

HideShow

id: string (required) Example: 853d5ee1-dbec-4015-843c-cb55943a1c7b
Id of an album.

Request

HideShow

Headers

Content-Type: application/json
Authorization: aa.bb.cc

Response 204

Complete Album ¶

Mark an album as completed
PUT`/albums/{id}/complete`

Example URI

PUT /albums/853d5ee1-dbec-4015-843c-cb55943a1c7b/complete

URI Parameters

HideShow

id: string (required) Example: 853d5ee1-dbec-4015-843c-cb55943a1c7b
Id of an album.

Request

HideShow

Headers

Content-Type: application/json
Authorization: aa.bb.cc

Response 204

Album publication ¶

Mark an album as published
PUT`/albums/{id}/publication`

Example URI

PUT /albums/853d5ee1-dbec-4015-843c-cb55943a1c7b/publication

URI Parameters

HideShow

id: string (required) Example: 853d5ee1-dbec-4015-843c-cb55943a1c7b
Id of an album.

Request

HideShow

Headers

Content-Type: application/json
Authorization: aa.bb.cc

Response 204

Videos ¶

Video with an ID ¶

Creation of a new video
POST`/videos/`

Example URI

POST /videos/

Request

HideShow

Headers

Content-Type: application/json
Authorization: aa.bb.cc

Body

{
  "title": "Video of Property 1234",
  "albumId": "853d5ee1-dbec-4015-843c-cb55943a1c7b"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "albumId": {
      "type": "string"
    }
  },
  "required": [
    "title",
    "albumId"
  ]
}

Response 201

HideShow

Headers

Location: /videos/8f2dbe69-b68f-4423-bc93-b8b036727a032

Fetch a specific video
GET`/videos/{id}`

Example URI

GET /videos/y53d5ee1-dbec-4015-843c-cb55943a1c7b

URI Parameters

HideShow

id: string (required) Example: y53d5ee1-dbec-4015-843c-cb55943a1c7b
Id of a video.

Request

HideShow

Headers

Content-Type: application/json
Authorization: aa.bb.cc

Response 200

HideShow

Body

{
    "_id": "y53d5ee1-dbec-4015-843c-cb55943a1c7b",
    "name": "Listings Madrid - 123124",
    "albumId": "853d5ee1-dbec-4015-843c-cb55943a1c7b"
    "platforms": [
        {
            "name": "youtube",
            "videoId": "123124",
            "videoURL": "http://youtu.be/123124"
        }
    ]
    "creationUser": "maikel@spotahome.com",
    "updateUser": "hugo@spotahome.com",
    "creationDate": "2017-01-03T09:00:00+01:00",
    "updateDate": "2017-01-03T09:00:00+01:00"
}

Response 404

HideShow

Headers

Content-Type: application/json

Body

{
  "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
  "title": "Not Found",
  "status": 404,
  "detail": "Video 'y53d5ee1-dbec-4015-843c-cb55943a1c7b' not found"
}

Video chunks upload ¶

Upload a video chunk
POST`/videos/{id}/chunks`

Example URI

POST /videos/853d5ee1-dbec-4015-843c-cb55943a1c7b/chunks

URI Parameters

HideShow

id: string (required) Example: 853d5ee1-dbec-4015-843c-cb55943a1c7b
Id of a video.

Request

HideShow

Headers

Content-Type: application/json

Response 200

Verify a video chunk
GET`/videos/{id}/chunks`

Example URI

GET /videos/853d5ee1-dbec-4015-843c-cb55943a1c7b/chunks

URI Parameters

HideShow

id: string (required) Example: 853d5ee1-dbec-4015-843c-cb55943a1c7b
Id of a video.

Request

HideShow

Headers

Content-Type: application/json

Response 200

Response 404

Finish Video chunks upload ¶

Finish the upload of the chunks
PUT`/albums/{id}/chunks/finish`

Example URI

PUT /albums/853d5ee1-dbec-4015-843c-cb55943a1c7b/chunks/finish

URI Parameters

HideShow

id: string (required) Example: 853d5ee1-dbec-4015-843c-cb55943a1c7b
Id of a video.

Request

HideShow

Headers

Content-Type: application/json
Authorization: aa.bb.cc

Response 204

Headers ¶

User Impersonation ¶

Albums ¶

Albums ¶

Creation of a new albumPOST/albums

Example URI

Headers

Body

Schema

Headers

Retrieve albums by criteriaGET/albums{?categoryId}{?reference}{?page}{?itemsPerPage}

Example URI

Headers

Headers

Body

Album with an ID ¶

Fetch single albumGET/albums/{id}

Example URI

Headers

Headers

Body

Update single albumPUT/albums/{id}

Example URI

Headers

Body

Schema

Headers

Delete single albumDELETE/albums/{id}

Example URI

Headers

Complete Album ¶

Mark an album as completedPUT/albums/{id}/complete

Example URI

Headers

Album publication ¶

Mark an album as publishedPUT/albums/{id}/publication

Example URI

Headers

Videos ¶

Video with an ID ¶

Creation of a new videoPOST/videos/

Example URI

Headers

Body

Schema

Headers

Fetch a specific videoGET/videos/{id}

Example URI

Headers

Body

Headers

Body

Video chunks upload ¶

Upload a video chunkPOST/videos/{id}/chunks

Example URI

Headers

Verify a video chunkGET/videos/{id}/chunks

Example URI

Headers

Finish Video chunks upload ¶

Finish the upload of the chunksPUT/albums/{id}/chunks/finish

Example URI

Headers

Headers

User Impersonation

Creation of a new album
POST`/albums`

Retrieve albums by criteria
GET`/albums{?categoryId}{?reference}{?page}{?itemsPerPage}`

Fetch single album
GET`/albums/{id}`

Update single album
PUT`/albums/{id}`

Delete single album
DELETE`/albums/{id}`

Mark an album as completed
PUT`/albums/{id}/complete`

Mark an album as published
PUT`/albums/{id}/publication`

Creation of a new video
POST`/videos/`

Fetch a specific video
GET`/videos/{id}`

Upload a video chunk
POST`/videos/{id}/chunks`

Verify a video chunk
GET`/videos/{id}/chunks`

Finish the upload of the chunks
PUT`/albums/{id}/chunks/finish`