eBayConnect2017

{ “Tanya Vlahovic” }

{ “Senior Architect, Developer Ecosystem and Services” }

{Best Practices for Integrating with eBay RESTful APIs

}

Developer Conference

eBayConnect2017

Developer Conference

2

On a dark

background

On a dark

background

2

Adopting best

practices makes

integration successfulAPI Integrations

3

• Principles

• How to Optimize

• Simplify

• Safe Environment

Agenda

44

Buy

Sell

CommerceAPIs common

across buy and

sell activities

APIs that enable

sellers to manage

all aspects of their

eBay business at

scale

APIs that enable

shopping on eBay

from anywhere

online

55

Quality LevelsDocumented on

eBay Developer Portal

Beta

• Purpose is to release capabilities for feedback

• Opportunity to get an early access to new APIs before GA

• Changes are possible during Beta period

• GA may not be backward compatible with Beta

• https://api.ebay.com/commerce/taxonomy/v1_beta

General availability

• Purpose is to release features for production use

• Stable interface design

• https://api.ebay.com/sell/inventory/v1

6

On a dark

background

On a dark

background

Changes to API may

not be backward

compatible and can

occur at any time

Experiment

al

capabilities

The purpose is

exploring, testing,

and feedback

Experimental Capabilities

The purpose is exploring,

testing and feedback

7

Extensibility & VersioningAll major/minor releases are communicated

and documented on eBay Developer Portal

8

On a dark

background

On a dark

background

Security & API Access

eBay APIs follow strong

security policies

An access token

is required for all

eBay APIs

99

API Scope

Buy / Browse https://api.ebay.com/oauth/api_scope

Buy / Order https://api.ebay.com/oauth/api_scope/buy.order

Buy / Feed https://api.ebay.com/oauth/api_scope/buy.item.feed

Sell / Account https://api.ebay.com/oauth/api_scope/sell.account

Sell / Inventory https://api.ebay.com/oauth/api_scope/sell.inventory

Sell / Fulfillment https://api.ebay.com/oauth/api_scope/sell.fulfillment

Sell / Marketing https://api.ebay.com/oauth/api_scope/sell.marketing

Sell / Analytics https://api.ebay.com/oauth/api_scope/sell.analytics.readonly

Sell / Metadata https://api.ebay.com/oauth/api_scope

Commerce / Taxonomy https://api.ebay.com/oauth/api_scope

Authorization Scope Granularity

10

OAuth Tokens• Expired access token

Long-lived refresh tokens may be exchanged

for new short-lived access tokens

• Expired refresh token

Send a user to the authorization code

flow again

• Revoked, invalid or not authorized token

Send a user to the authorization code

flow again

• Refresh access token only when expired

• Ensure SECURE storage of tokens

1111

OAuth 2.0: Client CredentialsAuthorizationFlow

Application

1. Get access token with

client ID and secret

API

2. Call the API with

access token

api.ebay.com

API

Endpoint

Token

Endpoint

Authorization

Endpoint

Redirection

Endpoint

Authorization

API

1212

OAuth 2.0: Authorization Code Flow

Application

API

Authorization

Endpoint

Token

Endpoint

API

Endpoint

4. Get access token

with client ID and secret

api.ebay.com

1. Login

widget

2. Request authorization code

[User authentication and consent]

3. Authorization code

and redirect

5. Call the API with access token

Authorization

server

Redirection

Endpoint

1313

Request HTTP Status Code

Success 200, 201, 202, 204, 207

Client side failure 400, 401, 403, 404, 409, 429

System side failure 500, 502

HTTP Status Code and Headers + BodyDescribe the Message

1414

Requests and HTTP Headers

HTTP Header Purpose

Authorization Bearer token

Accept

Accept-Charset

Accept-Encoding

Accept-Language

Content negotiations

Content-Type

Content-Language

Media type of the request

X-EBAY-C-ENDUSERCTX Information about the user, such as physical location or affiliate ID

X-EBAY-C-MARKETPLACE-ID Marketplace ID that identifies the application’s/user’s business context

1515

Responses and HTTP Headers

HTTP Header Purpose

Content-Type

Content-Language

Media type of the response

Location Newly created resource

16

Paginated CollectionResourceGET https://api.ebay.com/buy/browse/v1/item_

summary/search?q=watch&limit=10&offset=0

{

"href":"https://api.ebay.com/buy/browse/v1/item_

summary/search?q=watch&limit=1&offset=0",

"total": 443896,

"next":"https://api.ebay.com/buy/browse/v1/item_summary/

search?q=watch&limit=1&offset=1",

"limit": 10,

"offset": 0,

"itemSummaries": [

{

"itemId": "v1|351825690866|620839999865",

"title": "Men's Stainless Steel Sports Watch",

…

},

…

]

}

17

Error HandlingHTTP status is either 4XX or 5XX

Collection of errors in response body

In case of critical errors, no other data is sent

back to the client

Clients to check the HTTP status code first

and proceed accordingly

{

"errors": [

{

"errorId": 15008,

"domain": "API_ORDER",

"category": "REQUEST",

"message": "Invalid field: itemId.",

"inputRefIds”:

["$.lineItemInputs[0].itemId"],

"parameters": [

{

"name": "itemId",

"value": ”v1|2200077988|0"

} ]

} ]

}

Error IDs are unique and intended for developer support

Error categories• APPLICATION (mapped to 5xx HTTP status code)

• BUSINESS (mapped to 409 HTTP status code)

• REQUEST (mapped to 4xx HTTP status code)

Messages are descriptive rather than generic

• Human readable

• Tell developers what went wrong and how to fix it

• Example: The credit card was declined. Use the updatePaymentInfo call

to change the payment information.

1818

Common Errors

Error

Category

HTTP

Status

Code Error Remediation

APPLICATION 502

500

Routing error

Any other internal error

Retry the request

REQUEST 401

403

404

429

400

Invalid access token

Access denied

Resource not found

Quota exceeded

Any other request error

Regenerate the access token

Make sure the access token has proper scopes

Fix resource URI

Reduce your request rate

Fix your request parameters and/or body

BUSINESS 409 Business policy violation Show the error message to the end user

19

WarningsCollection of warnings is retrieved

in case of noncritical errors

The request processing can

continue and the response is

considered successful

{

”warnings": [

{

"errorId": 12002,

"domain": "API_BROWSE",

"category": "REQUEST",

"message": " The deliveryOptions filter value is

invalid. For the valid values, refer to the API call

documentation.",

"parameters": [

{

"name": ”fieldName",

"value": ”deliveryOptions"

},

{

"name": ”filterValue",

"value": ”{LOCAL_PICKUP}"

} ]

} ]

}

2020

BulkRequest

Correlation

Bulk ResponseA collection of individual responses

Each response has a status and a collection of errors or warnings, if any

HTTP status code for partial success is 207

Correlation ID uniquely identifies single request

Present in each individual request and response

Either query parameters OR

A collection of individual requests

21

Bulk CallsPOST

https://api.ebay.com/sell/marketing/v1/ad_campaign/10001

741014/bulk_delete_ads_by_inventory_reference

{

"requests":[

{

"inventoryReferenceId":"66352443",

"inventoryReferenceType": "INVENTORY_ITEM"

},

{

"inventoryReferenceId":"66352444",

"inventoryReferenceType": "INVENTORY_ITEM"

} ]

}

{

"responses": [

{

"statusCode": 200,

"inventoryReferenceId":"66352443",

"inventoryReferenceType": "INVENTORY_ITEM",

"adIds": [ "10039758018" ]

},

{

"statusCode": 200,

"inventoryReferenceId":"66352444",

"inventoryReferenceType": "INVENTORY_ITEM",

"adIds": [ "10039759018" ]

}

]

}

2222

Asynchronous Requests

Used for capabilities that

might take too long to

complete

Application API

POST /task

202 Accepted

Location: /task/abc

GET /task/abc

200 OK

GET /resource/xyz

200 OK

23

Asynchronous CallsPOST

https://api.ebay.com/sell/marketing/v1/ad_report_task

{

"reportType":

"CAMPAIGN_PERFORMANCE_REPORT",

"dateTo": "2017-01-30T00:00:00.000Z",

"metricKeys": [ "CLICKS" ],

…

"dateFrom": "2017-01-10T00:00:00.000Z",

"marketplaceId": "EBAY-US",

"reportFormat": "TSV_GZIP",

"campaignIds": [ "10000000019" ]

}

GET

https://api.ebay.com/sell/marketing/v1/ad_report_task/abc

{

"reportTaskId": "10000049014",

"reportType": "ACCOUNT_PERFORMANCE_REPORT",

"reportName": "10000049014.tsv.gz",

"reportTaskStatus": "SUCCESS",

…

"reportId": "10000049014",

"reportHref":

"https://plreports.qa.ebay.com/sell/marketing/v1/ad_report/

10000049014"

}

24

Enumerated values Handle gracefully newly added

enumeration values

Key-value pairs Handle gracefully newly added

key-value attributes

Errors In case of newly introduced errors,

fall back to the HTTP status code

to determine the best way to

address the error

Use Defensive Programming Techniques

25

On a dark

background

On a dark

background

RateLimitsSafeguard the

system from:

● Malicious attackers

● Spikes in consumption

● Inefficient applications

When reaching the limit

● Examine your requests

● Make your calls efficient

● Leverage bulk requests

● Throttle the volume

● File DTS ticket if needed

26

Do not use APIs in the

same way feeds are

used

Use Feed API to download

inventory and Search API for real-

time item retrieval

Cache static data Taxonomy and

Metadata APIs

Scope requests Get only the data that you

care most about

Use available filters

Specify fields and/or field groups

that you want returned

Improve Your Application

GET

https://api.ebay.com/buy/brows

e/v1/item_summary/search?q=

phone&category_ids=220

eBay categories are refreshed

on a periodic basis

eBay policies are periodically

changed

27

LoggingLog error responses

including HTTP headers

Details are needed when

contacting Developer Tech

Support (DTS)

28

Bulk requests Leverage bulk methods when

available

Reduce the bandwidth Use Accept-Encoding: gzip HTTP

header to reduce the bandwidth

needed for each request

Retry and implement

exponential backoff

Automate retries

Use longer waits between retries

for consecutive failed requests

Optimize Your Calls

Implement maximum delay and

number of retries

Only relevant to errors related

to rate limits, network issues

and response times

29

On a dark

background

On a dark

background

29

Well-tested and mature

The largest community

Simplified API integration with

Swagger Codegen

29

It makes the API easier to discover

and consume

OpenAPI InitiativeStandardized way to

describe RESTful APIs

Based on the Swagger

specification:

• Human readable

• Machine readable

3030

Demo

31

On a dark

background

On a dark

background

All eBay APIs are

deployed in sandboxSandboxA safe environment for

development and integration

with eBay APIs

32

On a dark

background

On a dark

background

32

ThenTest thoroughly

and iterate

Measure twice, cut once

FirstUnderstand

your goals

32

SecondUnderstand API capabilities and

limitations

FinallyDesign and implement

the integration

Thank you