Best Practices for Integrating with eBay RESTful APIs · Best Practices for Integrating with eBay...
Transcript of Best Practices for Integrating with eBay RESTful APIs · Best Practices for Integrating with eBay...
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
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
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