{"mock":"https://private-anon-797f845db7-ochreapi.apiary-mock.com/","production":"https://api.ochre.io/","proxy":"https://private-anon-797f845db7-ochreapi.apiary-proxy.com/"}

FORMAT: 1A HOST: https://api.ochre.io # Ochre API This document will expose all information related with all resources and actions. ## Resource access All endpoints are secured by default and can be accessed specifying a valid **access token** on every request. Access tokens can be issued by the **Ochre Auth** service: - https://auth.ochre.io/oauth2/token All API requests need to include the *Authorization* header with the token of *Bearer* type. - Authorization: Bearer [access_token] ### Sample API call flow #### Fetch a new access token ``` curl -X POST -d "client_id=[as provided]&client_secret=[as provided]&grant_type=client_credentials" https://auth.ochre.io/oauth2/token ``` - Access token TTL : 7200ms - A new token should be fetched upon expiration #### Call an API endpoint ``` curl -X GET \ https://api.ochre.io/v1/music/artists \ -H 'Authorization: Bearer [stored from previous ochre auth call]' \ -H 'Host: api.ochre.io' ``` ## Style guide * resources - `[api domain]/homepage/stores/{id}/[sub resources]` * url style - spinal-case ex: [api domain]/player/products/{id}/`sub-resources` * json properties style - camelCase ## Verbs * POST = create * GET = Read * PUT = Update/Replace * PATCH = Update/Modify * DELETE = Delete ## Status codes * detail the expected status code for each action according to the spec: https://tools.ietf.org/html/rfc7231 ## Custom headers Location related information will be picked up and aggregated on every request. This will be used to expose the correspondent data formats like currency and item availability. For server-to-server implementation that info needs to me mirrored from the original client request. That can be done by specifying the following headers: * X-Client-IP * X-Client-Currency (ISO 4217) * X-Client-Country-Code2 (ISO Alpha-2) ## Images All endpoints that return images hosted by ochre will react to **image_size** *GET* param. This will return all the images from a given response matching the size specified, if available. By default the api will return small images. + Sizes + XL + value: `xl` + width: `2000` + L + value: `l` + width: `1000` + M + value: `m` + width: `500` + XS + value: `s` + width: `250` + XS + value: `xs` + width: `125` + XSS + value: `xss` + width: `80` Sample request: `/music/releases/96596?image_size=m` This will return the artwork as a 500x500 image # Group CMS / Spaces A space represents the umbrella for all CMS based endpoints. It will hold general information about the purpose of all its sub-resources like view and modules Allows searching, getting the profile and sub-resources. ## Collection [/cms/spaces{?name,type,owner_id,owner_name,page,limit}] Allows actions on the spaces collection. ### Search [GET] + Parameters + name (optional, String) - space name (starting by) + type (optional, String) - space type + `artist` + `release` + `label` + `store` + `generic` (default) + owner_id (optional, String) - owner id + owner_name (optional, String) - owner name + page (optional, Number) - page number + default: 1 + limit (optional, Number) - maximum number of records per page. + default: 1 + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "summary": { "page": 1, "limit": 10, "totalPages": 1, "totalResults": 1 }, "results": [ { "id": 1, "type": "store", "catalog": { "id": 1, "name": "Bleep" }, "format": "web", "name": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png", "owner": { "id": 1, "name": "Bleep Ltd" }, "references": [ { "type": "store", "resource": { "id": 1, "title": "Bleep", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" } } ] } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ## Profile [/cms/spaces/{id}] Allows actions on a specific space. ### Get [GET] + Parameters + id: 1 (Long, required) - space id + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "id": 1, "type": "store", "catalog": { "id": 1, "name": "Bleep" }, "format": "web", "name": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png", "owner": { "id": 1, "name": "Bleep Ltd" }, "references": [ { "type": "store", "resource": { "id": 1, "title": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" } } ], "faviconUrl": "https://d1rgjmn2wmqeif.cloudfront.net/sf/s/1-1.png", "touchiconUrl": "https://d1rgjmn2wmqeif.cloudfront.net/sf/s/1-1.png", "metaDescription": "Bleep - We sell the best music from the best record labels and artists in the world. We specialise in finding the highest quality products regardless of format or genre. Including: Electronic Techno Electro House Experimental Grime Dubstep Hip Hop Alternative Indie and many more.", "keywords": [ "store", "ochre", "music", "physical", "digital" ], "settings": { "invitational": false }, "hasNavigationItems": true, "externalReferences": [ { "type": "link", "code":"facebook", "title":"Facebook", "value":"https://facebook.com/BleepBot" }, { "type": "account", "code":"facebook", "title":"Facebook", "value":"93984092349032482" }, { "type": "link", "code":"instagram", "title":"Instagram", "value":"http://instagram.com/bleep" }, { "type": "link", "code":"twitter", "title":"Twitter", "value":"https://twitter.com/bleep" } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 404 (application/json;charset=UTF-8) { "error": "resource not found", "code": 404 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ## Navigation items [/cms/spaces/{id}/navigation-items{?page,limit,group_id}] Lists all available navigation items for a given space. The results will include a structure that may hold more complex navigation structures with sub-items. ### List [GET] + Parameters + id: 1 (required, Long) - space id + page (optional, Number) - page number + default: 1 + limit (optional, Number) - maximum number of records per page. + default: 10 + group_id (optional, Long) - navigation group id + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "summary": { "page": 1, "limit": 10, "totalPages": 1, "totalResults": 2 }, "results": [ { "position": 1, "group" : { "id": 1, "name": "Main" }, "title": "Featured", "target": { "id": "2", "type": "view", "resource": { "id": 2, "title": "Music", "slug": "music", "imageUrl" : null } }, "subItems": [] }, { "position": 2, "group" : { "id": 1, "name": "Main" }, "title": "Genres", "target": { "id": "3", "type": "view", "resource": { "id": 3, "title": "Genres", "slug": "genres", "imageUrl" : null } }, "subItems": [] } ] } ## Views [/cms/spaces/{id}/views{?reference_type,type,reference_id,slug,title,page,limit}] Lists all views that belong the the given space. Allows all filters from the page search apart from the `space_id`. This param will be ignored. ### List [GET] + Parameters + id: 1 (required, Long) - space id + type (optional, String) - view type + `artist` + `release` + `homepage` + `article` + reference_type (optional, String) - reference type + `artist` + `release` + `label` + `store` + reference_id (optional, String) - reference id + slug (optional, String) - view slug + title (optional, String) - view title (starting by) + page (optional, String) - page number + default: 1 + limit (optional, Number) - maximum number of records per page + default: 10 + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "summary": { "page": 1, "limit": 10, "totalPages": 1, "totalResults": 7 }, "results": [ { "id": 1, "title": "Home", "description": null, "type": "homepage", "slug": null, "imageUrl" : null, "references": [], "space": { "id": 1, "type": "store", "format": "web", "name": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" } }, { "id": 2, "title": "Music", "description": null, "type": "homepage", "slug": null, "imageUrl" : null, "references": [], "space": { "id": 1, "type": "store", "format": "web", "name": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" } }, { "id": 3, "title": "Genres", "description": null, "type": "homepage", "slug": null, "imageUrl" : null, "references": [], "space": { "id": 1, "type": "store", "format": "web", "name": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" } }, { "id": 4, "title": "New Releases", "description": null, "type": "homepage", "slug": null, "imageUrl" : null, "references": [], "space": { "id": 1, "type": "store", "format": "web", "name": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" } }, { "id": 5, "title": "Pre-orders", "description": null, "type": "homepage", "slug": null, "imageUrl" : null, "references": [], "space": { "id": 1, "type": "store", "format": "web", "name": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" } }, { "id": 6, "title": "Newsletter", "description": null, "type": "homepage", "slug": null, "imageUrl" : null, "references": [], "space": { "id": 1, "type": "store", "format": "web", "name": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" } }, { "id": 7, "title": "Recommended", "description": null, "type": "homepage", "slug": null, "imageUrl" : null, "references": [], "space": { "id": 1, "type": "store", "format": "web", "name": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" } } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } # Group CMS / Views The view resource represents the customisable structure that will be used to organise the data through different modules. Using views will allow relying on ochre-platform tools to setup content and its disposition. ## Collection [/cms/views{?space_id,type,reference_type,reference_id,slug,title,page,limit}] Allows actions on the view collection. As a GET request it will only allow to filter by one reference. ### Search [GET] + Parameters + space_id (optional, Long) - space id + type (optional, String) - view type + `artist` + `release` + `homepage` + `article` + reference_type (optional, String) - reference type + `artist` + `release` + `label` + `store` + reference_id (optional, String) - reference id + slug (optional, String) - view slug + title (optional, String) - view title (starting by) + page (optional, Number) - page number + default: 1 + limit (optional, Number) - maximum number of records per page + default: 10 + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "summary": { "page": 1, "limit": 10, "totalPages": 1, "totalResults": 7 }, "results": [ { "id": 1, "title": "Home", "description": null, "type": "homepage", "slug": null, "imageUrl" : null, "references": [], "space": { "id": 1, "type": "store", "format": "web", "name": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" } }, { "id": 2, "title": "Music", "description": null, "type": "homepage", "slug": null, "imageUrl" : null, "references": [], "space": { "id": 1, "type": "store", "format": "web", "name": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" } }, { "id": 3, "title": "Genres", "description": null, "type": "homepage", "slug": null, "imageUrl" : null, "references": [], "space": { "id": 1, "type": "store", "format": "web", "name": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" } }, { "id": 4, "title": "New Releases", "description": null, "type": "homepage", "slug": null, "imageUrl" : null, "references": [], "space": { "id": 1, "type": "store", "format": "web", "name": "Bleep", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" } }, { "id": 5, "title": "Pre-orders", "description": null, "type": "homepage", "slug": null, "imageUrl" : null, "references": [], "space": { "id": 1, "type": "store", "format": "web", "name": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" } }, { "id": 6, "title": "Newsletter", "description": null, "type": "homepage", "slug": null, "imageUrl" : null, "references": [], "space": { "id": 1, "type": "store", "format": "web", "name": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" } }, { "id": 7, "title": "Recommended", "description": null, "type": "homepage", "slug": null, "imageUrl" : null, "references": [], "space": { "id": 1, "type": "store", "format": "web", "name": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" } } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ## Profile [/cms/views/{id}] Allows actions on a specific view. ### Get [GET] + Parameters + id: 1 (required, Long) - view id + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "id": 1, "title": "Home", "type": "homepage", "slug": null, "imageUrl" : null, "references": [], "space": { "id": 1, "type": "store", "format": "web", "name": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" }, "ancestors": [], "metatags": [ { "name": "og:title", "value": "Bleep - Home" }, { "name": "og:description", "value": "Bleep - We sell the best music from the best record labels and artists in the world. We specialise in finding the highest quality products regardless of format or genre. Including: Electronic Techno Electro House Experimental Grime Dubstep Hip Hop Alternative Indie and many more." }, { "name": "og:type", "value": "website" }, { "name": "og:image", "value": "https://d1rgjmn2wmqeif.cloudfront.net/st/s/1.png" }, { "name": "og:url", "value": "/" }, { "name": "og:site_name", "value": "Bleep" } ], "hasNavigationItems": false } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 404 (application/json;charset=UTF-8) { "error": "resource not found", "code": 404 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ## Modules [/cms/views/{id}/modules{?title,type,page,limit}] Lists all modules associated with the given view. This endpoint allows all module collection filters apart from `view_id`. ### List [GET] + Parameters + id: 1 (required, Long) - page id + title (optional, String) - module title (starting by) + type (optional, String) - module type + `product-block` + `list` + `text` + `image` + `video` + `banner` + `header` + page (optional, String) - page number + default: 1 + limit (optional, Number) - maximum number of records per page + default: 2 + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "summary": { "page": 1, "limit": 10, "totalPages": 1, "totalResults": 2 }, "results": [ { "id": 1, "title": "Album of the week", "type": "banner", "size": "large", "stylingReference": null, "itemCount": 0, "description": "Blackest Ever Black's chief junglist Pessimist turns in an extended subzero excursion, picking over the bones of skeletal breakbeat and industrial techno to create the most vivid fever of what constitutes darkside drum & bass in 2017...", "position": 1, "content": null, "target": null, "view": { "id": 1, "title": "Home", "slug": "home", "imageUrl" : null, "type": "homepage" } }, { "id": 2, "title": "Recommended", "type": "product-block", "size": "medium", "stylingReference": null, "itemCount": 27, "description": null, "position": 2, "content": null, "target":null, "view": { "id": 1, "title": "Home", "slug": "home", "imageUrl" : null, "type": "homepage" } } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } # Group CMS / Modules The category will allow to search modules, get a specific module profile as well as the inner items. ## Collection [/cms/modules{?view_id,title,type,page,limit}] Allows action on the module collection. ### Search [GET] + Parameters + view_id (optional, Long) - view id + title (optional, String) - module title (starting by) + type (optional, String) - module type Modules available are: + `product-block` + `list` + `text` + `image` + `video` + `banner` + `header` + page (optional, String) - page number + default: 1 + limit (optional, Number) - maximum number of records per page + default: 2 + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "summary": { "page": 1, "limit": 10, "totalPages": 1, "totalResults": 2 }, "results": [ { "id": 1, "title": "Album of the week", "type": "banner", "size": "large", "stylingReference": null, "itemCount": 0, "description": "Blackest Ever Black's chief junglist Pessimist turns in an extended subzero excursion, picking over the bones of skeletal breakbeat and industrial techno to create the most vivid fever of what constitutes darkside drum & bass in 2017...", "position": 1, "content": null, "target": null, "view": { "id": 1, "title": "Home", "slug": "home", "imageUrl" : null, "type": "homepage" } }, { "id": 2, "title": "Recommended", "type": "product-block", "size": "medium", "stylingReference": null, "itemCount": 27, "description": null, "position": 2, "content": null, "target": null, "view": { "id": 1, "title": "Home", "slug": "home", "imageUrl" : null, "type": "homepage" } } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ## Profile [/cms/modules/{id}] Gets a module profile ### Get [GET] + Parameters + id: 3 (required) + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "id": 3, "title": "Recommended", "type": "product-block", "size": "medium", "stylingReference": null, "itemCount": 27, "description": null, "position": 2, "content": null, "target": null, "view": { "id": 1, "title": "Home", "slug": "home", "imageUrl" : null, "type": "homepage" } } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 404 (application/json;charset=UTF-8) { "error": "resource not found", "code": 404 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ## Content items [/cms/modules/{id}/content-items{?page,limit}] Lists content items associated with the given module ### List [GET] + Parameters + id: 3 (required) + page (optional, String) - page number + default: 1 + limit (optional, Number) - maximum number of records per page + default: 2 + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "summary": { "page": 1, "limit": 20, "totalPages": 2, "totalResults": 2 }, "results": [ { "content": null, "description": null, "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/s/69701.jpg", "reference": { "id": 69701, "resource": { "artist": null, "id": 69701, "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/s/69701.jpg", "label": null, "title": "Mothers / Dark", "type": "single" }, "type": "release" }, "title": null }, { "content": null, "description": null, "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/s/65341.png", "reference": { "id": 65341, "resource": { "artist": null, "id": 65341, "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/s/65341.png", "label": null, "title": "Shinobi III- Return Of The Ninja Master", "type": "album" }, "type": "release" }, "title": null } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } # Group Retail / Stores This category exposes the store resource. It will allow searching stores and getting the related sub-resources. ## Collection [/retail/stores{?page,limit}] Allows actions on the store collection. ### Search [GET] + Parameters + page (optional, String) - page number + default: 1 + limit (optional, Number) - maximum number of records per page + default: 10 + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "summary": { "page": 1, "limit": 10, "totalPages": 1, "totalResults": 1 }, "results": [ { "id": 1, "code": "bleep", "title": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png", "references": [] } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ## Profile [/retail/stores/{id}] Gets a store profile. ### Get [GET] + Parameters + id:1 (required, Long) + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "id": 1, "code": "bleep", "title": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png", "settings": { "allowVouchers": true, "invitational": false }, "references": [] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 404 (application/json;charset=UTF-8) { "error": "resource not found", "code": 404 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } # Group Retail / Products This category allows exposing all product related data. It's possible search products, get a product profile and its sub-resources. ## Collection [/retail/products{?store_id,catalog_id,group_id,variant_group_id,title,type,reference_type,reference_id,from,to,format,universe,distribution,variant,page,limit}] Allows actions on the product collection. ### Search [GET] + Parameters + store_id (optional, Number) - filter by matching store + catalog_id (optional, Number) - restrict by the main catalog id + default: 1 + group_id (optional, Number) - allows grouping results by product group id + variant_group_id (optional, Number) - allows grouping results by variant group id + title (optional, String) - filter product title (starting by) + type (optional, String) - filter by type + `release` + `track` + `other` + reference_type (optional, String) - reference type + `artist` + `release` + `track` + `label` + reference_id (optional, String) - reference id + from (optional, String) - date string with format "yyyyMMdd" + to (optional, String) - date string with format "yyyyMMdd" + format (optional, String) - format title, ex: "vinyl", "mp3", "cd" + universe (optional, String) - universe name + music + clothing + merch + distribution (optional, String) - distribution type + physical + digital + variant (optional, String) - product variant name (mainly for clothing), ex: xs, s, l, xl, ... + page (optional, String) - page number + default: 1 + limit (optional, Number) - maximum number of records per page + default: 2 + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "summary": { "page": 1, "limit": 10, "totalPages": 1, "totalResults": 2 }, "results": [ { "id": 101, "universe": "music", "type": "release", "distribution": "physical", "universe": "music", "format": "vinyl", "variant": "12", "title": "Pre Dawn / Indoors", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "dateAvailable": "2017-10-27 00:00:00", "catNumber": "NONPLUS 043VL12", "upc": "191515890597", "group": { "id": 66075, "name": "Pre Dawn / Indoors" }, "variantGroup": { "id": 350798, "name": "Vinyl" }, "price": { "currency": { "code": "gbp", "position": 0, "symbol": "£" }, "value": 8.49, "discount": 0 }, "store": { "id": 1, "code": "BLEEP", "title": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" }, "references": [ { "id": "1", "type": "release", "resource": { "id": 1, "title": "Pre Dawn / Indoors", "type" : "single", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "artist": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "label": { "id": 1, "name": "Nonplus Records", "imageUrl": null } } } ] }, { "id": 201, "universe": "music", "type": "track", "distribution": "digital", "universe": "music", "format": "mp3", "variant": null, "title": "Pre Dawn", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "dateAvailable": "2017-10-27 00:00:00", "catNumber": null, "upc": null, "group": { "id": 66075, "name": "Pre Dawn / Indoors" }, "variantGroup": null, "price": { "currency": { "code": "gbp", "position": 0, "symbol": "£" }, "value": 1.49, "discount": 0 }, "store": { "id": 1, "code": "BLEEP", "title": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" }, "references": [ { "id": "1", "type": "release", "resource": { "id": 1, "title": "Pre Dawn / Indoors", "type" : "single", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "artist": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "label": { "id": 1, "name": "Nonplus Records", "imageUrl": null } } } ] } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ## Profile [/retail/products/{id}] Gets a given product resource. ### Get [GET] + Parameters + id: 20168512 (required) + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "id": 20168512, "catalog": { "id": 1, "name": "Bleep" }, "universe": "music", "type": "release", "distribution": "physical", "format": "vinyl", "variant": "12", "title": "Pre Dawn / Indoors", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "dateAvailable": "2017-10-27 00:00:00", "catNumber": "NONPLUS 043", "upc": "191515890597", "group": { "id": 66075, "name": "Pre Dawn / Indoors" }, "price": { "currency": { "code": "gbp", "position": 0, "symbol": "£" }, "value": 8.49, "discount": 0 }, "store": { "id": 1, "code": "BLEEP", "title": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" }, "description": null, "references": [ { "id": "1", "type": "release", "resource": { "id": 1, "title": "Pre Dawn / Indoors", "type" : "single", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "artist": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "label": { "id": 1, "name": "Nonplus Records", "imageUrl": null } } } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 404 (application/json;charset=UTF-8) { "error": "resource not found", "code": 404 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ## Availability [/retail/products/{id}/availability] Check for the given product stock and territory availability. This will gather the location data from the request by ip or custom location headers. ### Get [GET] + Parameters + id: 20168512 (required) + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "inStock": true, "inTerritory": true } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 404 (application/json;charset=UTF-8) { "error": "resource not found", "code": 404 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ## Bundle items [/retail/products/{id}/bundle-items{?page,limit}] Lists all inner products included on for a given bundle product. ### List [GET] + Parameters + id: 20168512 (required, Long) - product id + page (optional, String) - page number + default: 1 + limit (optional, Number) - maximum number of records per page + default: 10 + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "summary": { "page": 1, "limit": 10, "totalPages": 1, "totalResults": 2 }, "results": [ { "id": 101, "universe": "music", "type": "release", "distribution": "physical", "format": "vinyl", "universe": "music", "variant": "12", "title": "Pre Dawn / Indoors", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "dateAvailable": "2017-10-27 00:00:00", "catNumber": "NONPLUS 043VL12", "upc": "191515890597", "group": { "id": 66075, "name": "Pre Dawn / Indoors" }, "price": { "currency": { "code": "gbp", "position": 0, "symbol": "£" }, "value": 8.49, "discount": 0 }, "store": { "id": 1, "code": "BLEEP", "title": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" }, "references": [ { "id": "1", "type": "release", "resource": { "id": 1, "title": "Pre Dawn / Indoors", "type" : "single", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "artist": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "label": { "id": 1, "name": "Nonplus Records", "imageUrl": null } } } ] }, { "id": 201, "universe": "music", "type": "track", "distribution": "digital", "format": "mp3", "universe": "music", "variant": null, "title": "Pre Dawn", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "dateAvailable": "2017-10-27 00:00:00", "catNumber": null, "upc": null, "group": { "id": 66075, "name": "Pre Dawn / Indoors" }, "price": { "currency": { "code": "gbp", "position": 0, "symbol": "£" }, "value": 1.49, "discount": 0 }, "store": { "id": 1, "code": "BLEEP", "title": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" }, "references": [ { "id": "1", "type": "release", "resource": { "id": 1, "title": "Pre Dawn / Indoors", "type" : "single", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "artist": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "label": { "id": 1, "name": "Nonplus Records", "imageUrl": null } } } ] } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } # Group Retail / Carts This category exposes the cart resource and allows managing carts and their items. Cart results and their items will be restricted by store and requesting user. The specified access token will set the results available. ## Collection [/retail/carts{?store_id,page,limit}] Allows actions on the cart collection. ### Search [GET] + Parameters + store_id (optional, Long) - store id + page (optional, Number) - page number + default: 1 + limit (optional, Number) - maximum number of records per page + default: 10 + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "summary": { "page": 1, "limit": 10, "totalPages": 1, "totalResults": 2 }, "results": [ { "id": 1, "type": "cart", "store": { "id": 1, "title": "Bleep", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" }, "status": "active", "currency": "gbp", "itemCount": 1 }, { "id": 2, "type": "wish-list", "store": { "id": 1, "title": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" }, "status": "active", "currency": "gbp", "itemCount": 0 } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ### Add [POST] Creates a new cart resource. + Parameters + store_id (optional, Long) - store id + Request (application/json;charset=UTF-8) + Headers Authorization: Bearer [token] + Body { "type": "cart", "store": { "id": 1 } } + Response 201 (application/json;charset=UTF-8) { "id": 1, "type": "cart", "store": { "id": 1, "title": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" }, "status": "active", "currency": "gbp", "itemCount": 0, "vouchers": 0, "inCheckout": false, "costs": { "digital": 0, "preOrder": 0, "nonPreOrder": 0, "subTotal": 0, "discount": 0, "postage": 0, "total": 0 }, "shippingTo": "GB" } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ## Profile [/retail/carts/{id}] Gets a specific cart profile. Carts will include an estimated postage cost associated. ### Get [GET] + Parameters + id: 1 (required) + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "id": 1, "type": "cart", "store": { "id": 1, "title": "Bleep", "domain": "https://bleep.com", "tagLine" : "Bleep - music store", "imageUrl" : "https://d1rgjmn2wmqeif.cloudfront.net/sl/s/1-1.png" }, "status": "active", "currency": "gbp", "itemCount": 0, "vouchers": 0, "inCheckout": false, "costs": { "digital": 0, "preOrder": 0, "nonPreOrder": 8.49, "subTotal": 0, "discount": -5, "postage": 5, "total": 3.49 }, "shippingTo": "GB" } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 404 (application/json;charset=UTF-8) { "error": "resource not found", "code": 404 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ## Items [/retail/carts/{id}/items{?page,limit}] Allows action on the items that belong to a given cart. ### List [GET] + Parameters + id: 1 (required, Long) - cart id + page (optional, String) - page number + default: 1 + limit (optional, Number) - maximum number of records per page + default: 10 + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "summary": { "page": 1, "limit": 10, "totalPages": 1, "totalResults": 1 }, "results": [ { "id": 1, "quantity": 1, "product": { "id": 1, "type": "release", "format": "vinyl", "variant": "12", "title": "Pre Dawn / Indoors", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "references": [ { "id": "1", "type": "release", "resource": { "id": 1, "title": "Pre Dawn / Indoors", "type" : "single", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "artist": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "label": { "id": 1, "name": "Nonplus Records", "imageUrl": null } } }, { "id": 1, "resource": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "type": "artist" }, { "id": 1, "resource": { "id": 1, "name": "Nonplus Records", "imageUrl": null }, "type": "label" } ] }, "price": { "currency": { "code": "gbp", "position": 0, "symbol": "£" }, "value": 8.49, "discount": 0 } } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ### Add [POST] + Parameters + id:1 (required, Long) - cart id + Request (application/json;charset=UTF-8) + Headers Authorization: Bearer [token] + Body { "quantity": 1, "product": { "id": 101 } } + Response 201 (application/json;charset=UTF-8) { "id": 1, "quantity": 1, "product": { "id": 1, "type": "release", "format": "vinyl", "variant": "12", "title": "Pre Dawn / Indoors", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "references": [ { "id": "1", "type": "release", "resource": { "id": 1, "title": "Pre Dawn / Indoors", "type" : "single", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "artist": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "label": { "id": 1, "name": "Nonplus Records", "imageUrl": null } } }, { "id": 1, "resource": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "type": "artist" }, { "id": 1, "resource": { "id": 1, "name": "Nonplus Records", "imageUrl": null }, "type": "label" } ] }, "price": { "currency": { "code": "gbp", "position": 0, "symbol": "£" }, "value": 8.49, "discount": 0 } } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ## Item profile [/retail/carts/{id}/items/{item_id}] Allows actions on a specific cart item. Discounts will be calculated taking in consideration the vouchers that may be associated with the cart. ### Get [GET] + Parameters + id:1 (required, Long) - cart id + item_id:101 (required, Long) - cart item id + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "id": 101, "quantity": 1, "product": { "id": 1, "type": "release", "format": "vinyl", "variant": "12", "title": "Pre Dawn / Indoors", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "references": [ { "id": "1", "type": "release", "resource": { "id": 1, "title": "Pre Dawn / Indoors", "type" : "single", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "artist": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "label": { "id": 1, "name": "Nonplus Records", "imageUrl": null } } }, { "id": 1, "resource": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "type": "artist" }, { "id": 1, "resource": { "id": 1, "name": "Nonplus Records", "imageUrl": null }, "type": "label" } ] }, "price": { "currency": { "code": "gbp", "position": 0, "symbol": "£" }, "value": 8.49, "discount": 0 } } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 404 (application/json;charset=UTF-8) { "error": "resource not found", "code": 404 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ### Update [PUT] When accepted the full updated resource will be returned. Only quantities may be updated. + Parameters + id:1 (required, Long) - cart id + item_id:101 (required, Long) - cart item id + Request (application/json;charset=UTF-8) + Headers Authorization: Bearer [token] + Body { "quantity": 1 } + Response 202 (application/json;charset=UTF-8) { "id": 1, "quantity": 2, "product": { "id": 1, "type": "release", "format": "vinyl", "variant": "12", "title": "Pre Dawn / Indoors", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "references": [ { "id": "1", "type": "release", "resource": { "id": 1, "title": "Pre Dawn / Indoors", "type" : "single", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "artist": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "label": { "id": 1, "name": "Nonplus Records", "imageUrl": null } } }, { "id": 1, "resource": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "type": "artist" }, { "id": 1, "resource": { "id": 1, "name": "Nonplus Records", "imageUrl": null }, "type": "label" } ] }, "price": { "currency": { "code": "gbp", "position": 0, "symbol": "£" }, "value": 8.49, "discount": 0 } } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 404 (application/json;charset=UTF-8) { "error": "resource not found", "code": 404 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ### Delete [DELETE] + Parameters + id:1 (required, Long) - cart id + item_id:101 (required, Long) - cart item id + Response 202 (application/json;charset=UTF-8) { "detail":"resource deleted successfully", "code":202 } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 404 (application/json;charset=UTF-8) { "error": "resource not found", "code": 404 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ## Vouchers [/retail/carts/{id}/vouchers{?page,limit}] Allows actions on the voucher list that belong to the given cart. ### List [GET] + Parameters + id:1 (required, Long) - cart id + page (optional, String) - page number + default: 1 + limit (optional, Number) - maximum number of records per page + default: 10 + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "summary": { "page": 1, "limit": 10, "totalPages": 1, "totalResults": 0 }, "results": [ { "id": 1, "title": "Bleep T-Shirt Staff Discount", "description": null } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ### Add [POST] + Parameters + id:1 (required, Long) - cart id + Request (application/json;charset=UTF-8) + Headers Authorization: Bearer [token] + Body { "code": "3HDJJ24DD423" } + Response 201 (application/json;charset=UTF-8) { "id": 1, "title": "Bleep T-Shirt Staff Discount", "description": null } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } # Group Music / Labels Handles all label related data. `TODO: specify parameters` ## Collection [/music/labels{?page,limit}] Allows action on the label collection. ### Search [GET] + Parameters + page (optional, String) - page number + default: 1 + limit (optional, Number) - maximum number of records per page + default: 10 + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "summary": { "page": 1, "limit": 10, "totalPages": 1, "totalResults": 1 }, "results": [ { "id": 1, "name": "Nonplus Records", "imageUrl": null } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ## Profile [/music/labels/{id}] Gets a label profile. ### Get [GET] + Parameters + id: 163 (required) + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "id": 163, "name": "Warp Records", "imageUrl": null, "description": null, "externalReferences": [ { "code": "official", "title": "Official Website", "type": "url", "value": "http://warp.net/records" } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 404 (application/json;charset=UTF-8) { "error": "resource not found", "code": 404 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } # Group Music / Artists Handles all information related with artists ## Collection [/music/artists{?name,active,catalog_id,page,limit}] Allows actions on the artist collection. ### Search[GET] + Parameters + name (optional, String) - artist name (contains criteria) + active (optional, Boolean) - artist status + true + false + catalog_id (optional, Number) - main catalog id + page (optional, String) - page number + default: 1 + limit (optional, Number) - maximum number of records per page + default: 10 + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "summary": { "page": 1, "limit": 10, "totalPages": 1, "totalResults": 1 }, "results": [ { "id": 1, "name": "Burial", "active": true, "parent": null, "type": "artist", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg", "catalog": { "id": 1, "name": "Bleep" } } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ## Profile [/music/artists/{id}] Gets an artist profile. ### Get [GET] + Parameters + id: 1 (required) + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "id": 1, "name": "Burial", "active": true, "parent": null, "type": "artist", "description": "artist description", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg", "externalReferences": [], "dates": { "from": null, "to": null }, "catalog": { "id": 1, "name": "Bleep" } } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 404 (application/json;charset=UTF-8) { "error": "resource not found", "code": 404 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ## Releases [/music/artists/{id}/releases{?title,label_id,catalog_id,from,to,page,limit}] Lists releases from the given artist. ### List [GET] + Parameters + id: 1 (required, Number) - artist id + title (optional, String) - release title (starting by) + label_id (optional, String) - label id + catalog_id (optional, String) - catalog id + from (optional, String) - release date string with format "yyyyMMdd" + to (optional, String) - release date string with format "yyyyMMdd" + page (optional, String) - page number + default: 1 + limit (optional, Number) - maximum number of records per page + default: 1 + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "summary": { "page": 1, "limit": 10, "totalPages": 1, "totalResults": 1 }, "results": [ { "id": 1, "catalog": { "id": 1, "name": "Bleep" }, "title": "Pre Dawn / Indoors", "catalog": { "id": 1, "name": "Bleep" }, "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "type" : "single", "artist": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "label": { "id": 1, "name": "Nonplus Records", "imageUrl": null }, "formats": [ { "distribution": "physical", "code": "vinyl12", "variant": "12\\\"", "family": "vinyl" }, { "distribution": "physical", "code": "cd", "variant": null, "family": "cd" }, { "distribution": "digital", "code": "mp3", "variant": null, "family": null }, { "distribution": "digital", "code": "wav", "variant": null, "family": null } ] } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ## Tracks [/music/artists/{id}/tracks{?release_id,page,limit}] Lists tracks from the given artist. ### List [GET] + Parameters + id: 1 (required, Number) - artist id + release_id (optional, Number) - release id + page (optional, String) - page number + default: 1 + limit (optional, Number) - maximum number of records per page + default: 2 + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "summary": { "page": 1, "limit": 10, "totalPages": 1, "totalResults": 2 }, "results": [ { "id": 1, "title": "Pre Dawn", "length": 491, "streamable": true, "position": 1, "medium": { "number": 1, "position": 1 }, "release": { "id": 1, "title": "Pre Dawn / Indoors", "type" : "single", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "artist": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "label": { "id": 1, "name": "Nonplus Records", "imageUrl": null } } }, { "id": 2, "title": "Indoors", "length": 450, "streamable": true, "position": 2, "medium": { "number": 1, "position": 1 }, "release": { "id": 1, "title": "Pre Dawn / Indoors", "type" : "single", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "artist": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "label": { "id": 1, "name": "Nonplus Records", "imageUrl": null } } } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } # Group Music / Releases Handles all information related with releases. ## Collection [/music/releases{?title,artist_id,artist_name,label_id,catalog_id,from,to,page,limit}] Allows action on the release collection. ### Search[GET] + Parameters + title (optional, String) - release title (starting by) + artist_id (optional, Number) - artist id + artist_name (optional, String) - artist name (starting by) + label_id (optional, Number) - label id + catalog_id (optional, Number) - catalog id + from (optional, String) - release date string with format "yyyyMMdd" + to (optional, String) - release date string with format "yyyyMMdd" + page (optional, String) - page number + default: 1 + limit (optional, Number) - maximum number of records per page + default: 1 + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "summary": { "page": 1, "limit": 10, "totalPages": 1, "totalResults": 1 }, "results": [ { "id": 1, "catalog": { "id": 1, "name": "Bleep" }, "title": "Pre Dawn / Indoors", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "type" : "single", "artist": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "label": { "id": 1, "name": "Nonplus Records", "imageUrl": null }, "formats": [ { "distribution": "physical", "code": "vinyl12", "variant": "12\\\"", "family": "vinyl" }, { "distribution": "physical", "code": "cd", "variant": null, "family": "cd" }, { "distribution": "digital", "code": "mp3", "variant": null, "family": null }, { "distribution": "digital", "code": "wav", "variant": null, "family": null } ] } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ## Profile [/music/releases/{id}] Gets a given release profile. ### Get [GET] + Parameters + id: 2 (required) + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "id": 2, "catalog": { "id": 1, "name": "Bleep" }, "title": "Pre Dawn / Indoors", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "type" : "single", "artist": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "label": { "id": 1, "name": "Nonplus Records", "imageUrl": null }, "description": "Burial lands on Boddika's Nonplus label with two dark and shadowy rollers that hark back to the label's roots in expertly engineered DNB. Pre Dawn/Indoors further mines the 2 step techno sound he made his own on his recent Hyperdub-plate, while traversing musical directions previously only hinted at ten years ago when he first unleashed this sound upon us with the game changer that was Untrue.", "releaseDate" : "2017-10-27 00:00:00", "trackCount": 2, "totalLength": 924.6, "catNumber": "NONPLUS 043", "externalReferences": [ { "code": "spotify", "title": "Spotify", "type": "url", "value": "https://dummy-spotify-link.com" } ], "formats": [ { "distribution": "physical", "code": "vinyl12", "variant": "12\\\"", "family": "vinyl" }, { "distribution": "physical", "code": "cd", "variant": null, "family": "cd" }, { "distribution": "digital", "code": "mp3", "variant": null, "family": null }, { "distribution": "digital", "code": "wav", "variant": null, "family": null } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 404 (application/json;charset=UTF-8) { "error": "resource not found", "code": 404 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ## Tracks [/music/releases/{id}/tracks{?artist_id,page,limit}] Lists tracks from a given release. ### List [GET] + Parameters + id: 2 (required, Number) - release id + artist_id (optional, Number) - artist id + page (optional, String) - page number + default: 1 + limit (optional, Number) - maximum number of records per page + default: 10 + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "summary": { "page": 1, "limit": 10, "totalPages": 1, "totalResults": 2 }, "results": [ { "id": 1, "title": "Pre Dawn", "length": 491, "streamable": true, "imageUrl": null, "position": 1, "medium": { "number": 1, "position": 1 }, "release": { "id": 1, "title": "Pre Dawn / Indoors", "type" : "single", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "artist": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "label": { "id": 1, "name": "Nonplus Records", "imageUrl": null } } }, { "id": 2, "title": "Indoors", "length": 450, "streamable": true, "imageUrl": null, "position": 2, "medium": { "number": 1, "position": 1 }, "release": { "id": 1, "title": "Pre Dawn / Indoors", "type" : "single", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "artist": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "label": { "id": 1, "name": "Nonplus Records", "imageUrl": null } } } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } # Group Music / Tracks Handles all information related with tracks. ## Collection [/music/tracks{?artist_id,release_id,page,limit}] Allows action on the track collection. ### Search [GET] + Parameters + artist_id (optional, Number) - artist id + release_id (optional, Number) - release id + page (optional, String) - page number + default: 1 + limit (optional, Number) - maximum number of records per page + default: 10 + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "summary": { "page": 1, "limit": 10, "totalPages": 1, "totalResults": 2 }, "results": [ { "id": 1, "title": "Pre Dawn", "length": 491, "streamable": true, "imageUrl": null, "position": 1, "medium": { "number": 1, "position": 1 }, "release": { "id": 1, "title": "Pre Dawn / Indoors", "type" : "single", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "artist": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "label": { "id": 1, "name": "Nonplus Records", "imageUrl": null } } }, { "id": 2, "title": "Indoors", "length": 450, "streamable": true, "imageUrl": null, "position": 2, "medium": { "number": 1, "position": 1 }, "release": { "id": 1, "title": "Pre Dawn / Indoors", "type" : "single", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "artist": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "label": { "id": 1, "name": "Nonplus Records", "imageUrl": null } } } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ## Profile [/music/tracks/{id}] Gets a given track profile. ### Get [GET] + Parameters + id: 1 (required) + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "id": 1, "title": "Pre Dawn", "length": 491, "streamable": true, "imageUrl": null, "position": 1, "medium": { "number": 1, "position": 1 }, "release": { "id": 1, "title": "Pre Dawn / Indoors", "type" : "single", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "artist": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "label": { "id": 1, "name": "Nonplus Records", "imageUrl": null } }, "isrc": "GB2HB1700166", "credits": [ { "type": "composer", "value": "composer name" }, { "type": "copyright", "value": "copyright owner name" } ], "notes": null } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 404 (application/json;charset=UTF-8) { "error": "resource not found", "code": 404 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ## Media items [/music/tracks/{id}/media-items{?type,format,service,catalog_id,from,to,include_references,page,limit}] Lists all media items associated with the given track. ### List [GET] + Parameters + id: 1 (required, Number) - track id + type (optional, String) - media item type + audio + video + image + format (optional, String) - media item format + mp3 + external_id + link + embed + service (optional, String) - source service name, ex: ochre, youtube, etc... + catalog_id (optional, String) - catalog id + from (optional, String) - release date string with format "yyyyMMdd" + to (optional, String) - release date string with format "yyyyMMdd" + include_references (optional, boolean) - sets if references are to be included in the response + default: true + page (optional, String) - page number + default: 1 + limit (optional, Number) - maximum number of records per page + default: 5 + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "summary": { "page": 1, "limit": 10, "totalPages": 1, "totalResults": 5 }, "results": [ { "id": 1, "type": "audio", "catalog": { "id": 1, "name": "Bleep" }, "details": { "length": 200000, "playableLength": 60000, "playableStart": 0, "seekAllowed": true }, "releaseDate": "1993-05-31T22:00:00Z", "service": { "code": "ochre", "name": "Ochre" }, "format": "mp3", "quality": 320, "title": null, "description": null, "thumbnail_url": null, "content": "1111" }, { "id": 2, "type": "audio", "catalog": { "id": 1, "name": "Bleep" }, "details": null, "releaseDate": null, "service": { "code": "spotify", "name": "Spotify" }, "format": "embed", "quality": null, "title": null, "description": null, "thumbnail_url": null, "content": "https://open.spotify.com/embed/track/6RuKIUlAjLTUA1ARraObu0" }, { "id": 3, "type": "video", "catalog": { "id": 1, "name": "Bleep" }, "details": null, "releaseDate": null, "service": { "code": "youtube", "name": "YouTube" }, "format": "link", "quality": null, "title": null, "description": null, "thumbnail_url": null, "content": "https://www.youtube.com/watch?v=zzGoNQSfmWs" }, { "id": 4, "type": "audio", "catalog": { "id": 1, "name": "Bleep" }, "details": null, "releaseDate": null, "service": { "code": "soundcloud", "name": "SoundCloud" }, "format": "embed", "quality": null, "title": null, "description": null, "content": "https://w.soundcloud.com/player/?url=https%3A//api.soundcloud.com/tracks/345628440" }, { "id": 5, "type": "video", "catalog": { "id": 1, "name": "Bleep" }, "details": null, "releaseDate": null, "service": { "code": "vimeo", "name": "Vimeo" }, "format": "external_id", "quality": null, "title": null, "description": null, "content": "16967871" } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } # Group Content / Media items Endpoint description ## Collection [/content/media-items{?reference_type,reference_id,type,format,service,catalog_id,from,to,include_references,page,limit}] ### Search [GET] + Parameters + reference_type (optional, String) - reference type + `artist` + `release` + `track` + `product` + `product_group` + reference_id (optional, String) - reference id + type (optional, String) - media item type + audio + video + image + format (optional, String) - media item format + mp3 + external_id + link + embed + service (optional, String) - source service name, ex: ochre, youtube, etc... + catalog_id (optional, String) - catalog id + from (optional, String) - release date string with format "yyyyMMdd" + to (optional, String) - release date string with format "yyyyMMdd" + include_references (optional, boolean) - sets if references are to be included in the response + default: true + page (optional, String) - page number + default: 1 + limit (optional, Number) - maximum number of records per page + default: 5 + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "summary": { "page": 1, "limit": 10, "totalPages": 1, "totalResults": 5 }, "results": [ { "id": 1, "type": "audio", "catalog": { "id": 1, "name": "Bleep" }, "details": { "length": 200000, "playableLength": 60000, "playableStart": 0, "seekAllowed": true }, "releaseDate": "1993-05-31T22:00:00Z", "service": { "code": "ochre", "name": "Ochre" }, "format": "mp3", "quality": 320, "details": { "length": 200000, "playableLength": 60000, "playableStart": 0, "seekAllowed": true }, "title": null, "description": null, "thumbnailUrl": null, "asset": "1111" }, { "id": 2, "type": "audio", "catalog": { "id": 1, "name": "Bleep" }, "details": null, "releaseDate": null, "service": { "code": "spotify", "name": "Spotify" }, "format": "embed", "quality": null, "title": null, "description": null, "thumbnailUrl": null, "asset": "https://open.spotify.com/embed/track/6RuKIUlAjLTUA1ARraObu0" }, { "id": 3, "type": "video", "catalog": { "id": 1, "name": "Bleep" }, "details": null, "releaseDate": null, "service": { "code": "youtube", "name": "YouTube" }, "format": "link", "quality": null, "title": null, "description": null, "thumbnailUrl": null, "asset": "https://www.youtube.com/watch?v=zzGoNQSfmWs" }, { "id": 4, "type": "audio", "catalog": { "id": 1, "name": "Bleep" }, "details": null, "releaseDate": null, "service": { "code": "soundcloud", "name": "SoundCloud" }, "format": "embed", "quality": null, "title": null, "description": null, "thumbnailUrl": null, "asset": "https://w.soundcloud.com/player/?url=https%3A//api.soundcloud.com/tracks/345628440" }, { "id": 5, "type": "video", "catalog": { "id": 1, "name": "Bleep" }, "details": null, "releaseDate": null, "service": { "code": "vimeo", "name": "Vimeo" }, "format": "external_id", "quality": null, "title": null, "description": null, "thumbnailUrl": null, "asset": "16967871" } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500 } ## Profile [/content/media-items/{id}] ### Get [GET] + Parameters + id: 2055509 (required) + Request + Headers Authorization: Bearer [token] + Response 200 (application/json;charset=UTF-8) { "id": 201, "type": "video", "catalog": { "id": 1, "name": "Bleep" }, "details": { "length": 200000, "playableLength": 60000, "playableStart": 0, "seekAllowed": true }, "releaseDate": "1993-05-31T22:00:00Z", "service": { "code": "youtube", "name": "YouTube" }, "format": "link", "quality": null, "title": null, "description": null, "thumbnailUrl": null, "asset": "https://www.youtube.com/watch?v=zzGoNQSfmWs", "references": [ { "id": 1, "type": "track", "resource": { "id": 1, "title": "Pre Dawn", "length": 491, "streamable": true, "imageUrl": null, "release": { "id": 1, "title": "Pre Dawn / Indoors", "type" : "single", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/90434-1.jpg", "artist": { "id": 1, "name": "Burial", "imageUrl": "https://d1rgjmn2wmqeif.cloudfront.net/r/b/13113.jpg" }, "label": { "id": 1, "name": "Nonplus Records", "imageUrl": null } } } } ], "alternativeItems": [ { "asset": "111", "catalog": { "id": 1, "name": "Bleep" }, "description": null, "format": "mp3", "id": 101, "releaseDate": "2018-08-07T00:00:00Z", "service": { "code": "ochre", "name": "Ochre" }, "thumbnailUrl": null, "title": "Pre Dawn", "type": "audio", "url": null } ], "credits": [ { "type": "producer", "value": "producer name" } ] } + Response 400 (application/json;charset=UTF-8) { "error": "bad request", "code": 400 } + Response 401 (application/json;charset=UTF-8) { "error": "unauthorized", "code": 401 } + Response 404 (application/json;charset=UTF-8) { "error": "resource not found", "code": 404 } + Response 500 (application/json;charset=UTF-8) { "error": "internal server error", "code": 500