Stock Affiliate API workflow

Transcription

1 Adbe Stck Stck Affiliate API wrkflw The purpse f this dcument is t illustrate the verall prcess and technical wrkflw fr Adbe Stck partners wh want t integrate the Adbe Stck Search API int their applicatins. The Stck API allws yu t interact with Adbe Stck prgrammatically, rather than thrugh a user interface. Dcument cntents Intrductin... 1 Wrkflw verview... 1 Adbe I/O Cnsle wrkflw... 2 Creating a Search API applicatin... 3 Authenticating requests...3 Applicatin flw details... 4 Intrductin This paper utlines the wrkflw fr Adbe Stck affiliate partners. This culd include: Stck aggregatr sites. Aggregatrs have websites that may include stck cntent frm multiple prviders, including Adbe Stck, as well as their wn cllectin f assets. Adbe Stck search culd be added t the site, with links referring users back t the Adbe Stck website fr cmpleting the sale. The aggregatr culd receive a cmmissin fee if it leads t a new subscriptin. Independent develpers. The affiliate wrkflw is als suitable fr develpers wh want t get familiar with the Adbe Stck APIs, and/r want t cnsume them within the cntext f a test applicatin. In this case, n cmmissins n sales wuld ccur (it wuld nt be expected that the test applicatin wuld create any sales). Wrkflw verview

2 Adbe Stck Enterprise Service Accunt API wrkflw Assuming that the partner wants t receive cmmissins, the prcess begins with a cntracting prcess with the Adbe Stck Business Develpment team. During this prcess, the partner will enrll in the Adbe Affiliate prgram, and accept the terms f use fr the Stck API. Cntracting and cmmissins are beynd the scpe f this dcument. T get mre infrmatin, please cntact Grp-AdbeStckPartnerships@adbe.cm. Whether the partner ges the cmmissin rute r simply wants t test the APIs, the rest f the prcess is the same. Develpers will register their applicatin using the Adbe I/O Cnsle, which will allw it access Stck APIs. The result f this prcess is an API key which is used t allw requests. Nw the integratr can start writing an applicatin that uses the Stck API t make search queries and get back image thumbnail results, which the applicatin will display. When the website end-user wishes t license an asset, the API prvides a jump URL which links directly t the details page n the Stck site where the user can sign up fr a plan. If the partner has signed up as an affiliate, the transactin will be tracked by Adbe and referral credit given back t the partner. Adbe I/O Cnsle wrkflw T use the Adbe Stck API, yu need t generate an applicatin key n the Adbe I/O Cnsle. Adbe I/O will whitelist this key and permit yur applicatin access t the APIs. Access the Adbe I/O Cnsle here: If yu d nt already have an Adbe ID, yu will need t create ne (fr free). Click the New Integratin buttn. Select the fllwing items, clicking Cntinue each time: Access an API > Adbe Stck > OAuth 1 integratin > New integratin This pens a screen where yu will enter yur integratin details: Name: Yur applicatin s name. This will nt be sent in yur API requests; hwever, a gd practice might be t give it the same web-friendly name yu will be using later when sending the required X-Prduct header (see Applicatin flw details, belw). Descriptin: E.g., Integratin f Stck API with MyWebsite.cm. Platfrm: Chse Web. This dcument assumes yu are authring a web/brwser-based applicatin as ppsed t a native ios r Andrid applicatin. Default redirect URI: As mentined in the ftnte abve, this field is nly required fr true OAuth integratins. Since this is actually an API Key integratin, this field is nt required. Hwever, yu must still fill it ut with smething. 1 The label OAuth is a misnmer. This is nt a true OAuth integratin, but an API Key integratin. Adbe Stck supprts three integratin types: Service Accunt, (true) OAuth, and API Key. The Adbe I/O Cnsle currently nly shws tw f thse ptins, and the API Key integratin is incrrectly labeled as OAuth, which is a bug. Page 2

3 Adbe Stck Enterprise Service Accunt API wrkflw Yu can use any arbitrary URL address (e.g., Redirect URI pattern: Same as abve; this field is nt required fr this integratin methd but yu must still put sme infrmatin here. Yu may enter the same URL as abve, but yu must escape perids (.) with \\. Ex: Once saved, the I/O Cnsle will generate a few pieces f data. The nly infrmatin yu need frm this screen is the API Key (Client ID). Yu d nt need the Client Secret fr this wrkflw. Cpy this smewhere fr the next step. This whitelists yur identifies yur applicatin, and is required fr receiving yur cmmissin (if yu went thrugh the partner cntract prcess). Creating a Search API applicatin Whether yu are creating a standalne web applicatin r integrating Stck Search int yur existing website r applicatin, the prcess is the same. Fr the purpses f this dcument, the term applicatin will describe the integratin yu are creating. The applicatin will make and receive RESTful calls between the end-user and Adbe Stck, parse the JSON respnse, and update the UI t shw the search results. Authenticating requests The Stck Search API nly requires API key authenticatin; therwise, requests are essentially annymus. Cnsequently, this integratin type cannt be used by itself fr API methds that require user- r rganizatin-level authenticatin. Fr example, the API key alne cannt be used t license images r get a past license histry. Stck headers and example With each HTTP request, yu will set mandatry and ptinal headers in additin t any search query parameters. Required: x-api-key: The API key assigned t yur applicatin integratin when yu signed up thrugh the Adbe I/O Cnsle, abve. It is a GUID-style string, generated prgrammatically. X-Prduct: The name f yur prduct r website that is using the API. This can be whatever yu want, hwever best practice is that yu use smething a title similar t the integratin name yu created n the Adbe I/O Cnsle. Optinal: Authrizatin: Access tken issued by Adbe t an end user r rganizatin. If included in search requests, this will indicate whether assets are already licensed r nt. Page 3

4 Adbe Stck Enterprise Service Accunt API wrkflw As mentined abve, this requires a different kind f wrkflw. The Affiliate wrkflw des nt prvide authrizatin, and it is implied that integratins will be making annymus requests nly. X-Request-Id: A unique request identifier that yu define, used t trace the request in lgs. The lgs are nt accessible t partners, but Adbe may request that yu add this header t help trublesht issues. Mst search queries are issued with an HTTP GET request, hwever an HTTP POST is required if yu want t uplad an image fr similarity search. Here are examples f using required headers. Sample request with headers GET /Rest/Media/1/Search/Files?lcale=en_US &search_parameters[wrds]=flamings HTTP/1.1 Hst: stck.adbe.i X-Prduct: CFSTest/1.0 X-API-Key:...0e3f Applicatin flw details It is assumed the applicatin will prvide a UI fr searching and displaying results, since the Stck APIs d nt prvide this. 1. The wrkflw begins when the partner s website custmer, the end-user, perfrms a search n the partner s site fr Adbe Stck images. Search parameters indicate what kind f search t perfrm (fr example a wrd search, search by ID, search by artist, r a visual similarity search), as well as what filters t apply (search nly n phts, vectrs, vides, templates, etc.) 2. The partner s web applicatin submits a Search/Files request t the Stck API. Search/Files request 1 (using curl syntax) curl -X GET \ ' en-us&search_parameters%5bwrds%5d=kittens' \ -H 'x-api-key:...0e3f' \ -H 'x-prduct: TeamCFS_1.0' The request supplies any number f search parameters, filters and respnse fields. 3. The Stck API respnds with a JSON bject cntaining the number f results (nb_results), and a files array f metadata fr each asset fund. 1 Fr a cmplete reference, see Page 4

5 Adbe Stck Enterprise Service Accunt API wrkflw Search/Files respnse "nb_results": , "files": [ "id": , "title": "five kittens", "width": 2500, "height": 1667, "creatr_name": "adyaft", "creatr_id": , "thumbnail_url": " JUFSzXW7j5cGiKDT9.jpg", "thumbnail_html_tag": "<img src=\" 7LzGJUFSzXW7j5cGiKDT9.jpg\" alt=\"five kittens\" title=\"pht: five kittens\" zm_rati=\"1.25\" zm_depth_max=\"2\" />", "thumbnail_width": 500, "thumbnail_height": 334, "media_type_id": 1, "vectr_type": null, "cntent_type": "image/jpeg", "categry": "id": 44, "name": "Cats" }, "premium_level_id": 0 },... ] } Respnse is truncated t shw ne file result. The API allws full cntrl ver what fields are returned in the search results. 4. The partner s applicatin parses the results and shws thumbnails fr each asset and any ther data (such as keywrds) that may help the user refine their search. The end-user may use watermarked versins f images until they are ready t license. 5. If the partner wants t allw the user t see mre details abut an asset, the applicatin can submit additinal queries t get an array f similar images r mre images within that same series. Search fr similar image curl -X GET \ ' US&search_parameters%5Bsimilar%5D=% &search_parameters%5Bsi milar_image%5d=1&search_parameters%5blimit%5d=5' \ Page 5

6 Adbe Stck Enterprise Service Accunt API wrkflw -H 'x-api-key:...0e3f' \ -H 'x-prduct: TeamCFS_1.0' 6. If the user wants t license the image, yu can give them a link t the detail page f that asset n the Adbe Stck website, via a jump URL prvided by the API. Yu get this URL in yur respnse data by adding the result_clumns[]=details_url parameter. Nte that adding any result_clumns parameter t the query string will cause nly thse fields t appear in the JSON results. Yu can add multiple result_clumns cmmands t get exactly the results yu want. Filter search fr details_url and title nly fr ID curl -X GET \ ' US&search_parameters%5Bmedia_id%5D= &result_clumns%5b%5d=title&result_clumns%5b%5d=details_url' \ -H 'x-api-key:...0e3f' \ -H 'x-prduct: TeamCFS_1.0' In the jump URL returned, the as_channel=affiliate and ther parameters allws Adbe tracking s that yur applicatin gets referral credit. Be sure nt t remve them. Filtered results "files": [ "title": "five kittens", "details_url": " &as_cntent=8af2713e4ace ddfd04a94b6ac" } ] }. Page 6