commercetools™ API

Technical Concepts

All Rights Reserved © 2017 1

Content

• Hosts

• Authorization

• Managing Resources

• Common API Types

• API Errors

All Rights Reserved © 2017 2

Hosts & Regions

EU US
Merchant mc.commercetools.com mc.commercetools.co
Center

Host api.sphere.io api.commercetools.co

… … …

All Rights Reserved © 2017 3

Authorization

All Rights Reserved © 2017 4

Authorization – OAuth2

• Clients must obtain an access token.

• The access token is required to make authorized requests.

Authorization: Bearer {access_token}

• Default is 48 hours.

All Rights Reserved © 2017 5

Authorization – An Example with cURL
local enc="$(echo -n "${CLIENT_ID}:${CLIENT_SECRET}")”

local result="$(curl -s -X POST -H "Authorization: Basic ${enc}" -d

"grant_type=client_credentials&scope=manage_project:${PROJECT_KEY}"

https://auth.sphere.io/oauth/token)"

Example Response

"access_token": "vkFuQ6oTwj8_Ye4eiRSsqMeqLYxxxxxx",

"expires_in": 172800, // seconds (48 hours)

"scope": "manage_project:{projectKey}",

"token_type": "Bearer”

curl -s "https://api.sphere.io/${PROJECT_KEY}/product-projections?access_token=${ACCESS_TOKEN}"

https://github.com/sphereio/sphere-hello-api/blob/master/curl/hello-api

All Rights Reserved © 2017 6

Authorization – Flows

• Client Credentials Flow

• Required: client_id and client_secret
• Optional: scope
• Password Flow
• Required: client_id, client_secret, username (email) and unencrypted password
• Response include: refresh_token, in addition to access_token.
• Refresh Token Flow
• Anonymous Session
• Access token is associated with an anonymousId
• Optional: anonymous_id (if not supplied, the ID is generated by the API).

All Rights Reserved © 2017 7

Authorization – Scopes

• Scopes: sets of permissions.

• scope is optional when requesting an access token. Default: all scopes!
• Admin Center > Developers > API Clients > Add API Client.
• Enable scope:

{scope}:{projectKey}

• manage_project: full access. (Admin permissions)

• manage_products: creating, modifying, and viewing anything related to products.
• view_products: viewing anything related to products.
• manage_orders: creating, modifying, and viewing anything related to orders, carts, and shipping.
• create_anonymous_token: creating tokens for anonymous sessions.
• view_project_settings: viewing project settings.
• …

All Rights Reserved © 2017 8

Managing Resources

All Rights Reserved © 2017 9

The Classical Model

Client

Model
API Database

All Rights Reserved © 2017 10

All Rights Reserved © 2017 11
CQRS Command Query Responsibility Segregation

API Write Model

Client

Database

Model
API

All Rights Reserved © 2017 12

CQRS Command Query Responsibility Segregation

Query Command

• Read • Create, update, delete.

• Queries are handled faster. • POST, DELETE.

• Single response: GET. • Command are handled asynchronously.

• Update commands are further refined

e.g. set, change, remove.

All Rights Reserved © 2017 13

Event Sourcing

API CMD Events

Event Store
Client

Read Models
API Database

All Rights Reserved © 2017 14

Updating Resources

• id or key to identify the resource on which to apply the changes.

• Version of the resource.

• Resource specific actions.

• Max. 500 actions/request.

Example of an update payload

All Rights Reserved © 2017 15

User-defined fields / platform-generated fields

Object
Object Draft

User-defined fields:
Object Draft • Key
• Name
User-defined fields: Create Object • etc.
• Key
• Name Platform-generated fields:
• etc. • Id
• Version
• Created at
• Last modified at

All Rights Reserved © 2017 16

Draft vs. Resource – e.g. Order
Order
OrderFromCartDraft

User-defined fields:
• orderNumber
OrderFromCartDraft • paymentState

User-defined fields: Create Order

• id* (cart id) Platform-generated fields:
• version* (cart) • id (order id)
• orderNumber • version
• paymentState • createdAt
• lastModifiedAt
• customerId
• lineItems
• totalPrice
• …

All Rights Reserved © 2017 17

Optimistic Concurrency Control (OCC)
• Correct update of data.

• Concurrent multiple transactions.

• Latest version number.

• Only one version at a time.

• The version increases on every update.

Create Update Update

product myProduct product myProduct again myProduct
version: 1 version: 2 version: x

All Rights Reserved © 2017 18

Strong vs. Eventual Consistency

Every resource provides read-after-write (a.k.a. strong) consistency.

Eventual Consistency: changes are done with some delay.

Examples

Changes on Affected by Changes

(strong consistent) (eventual consistent)

Product Discounts Prices

Products Search Index

All Rights Reserved © 2017 19

Common API Types

All Rights Reserved © 2017 22

Localized String

It is a JSON object.

{
"de": "Hundefutter",
"en": "dog food”
}

Used mainly for fields: name, slug, description, and meta data fields.

All Rights Reserved © 2017 23

Reference

A (loose) reference

• specifies the type of the referred resource and its id.

• reduces the number of requests.

{
"typeId": "product",
"id": "d1229e6f-2b79-441e-b419-180311e52754”
}

Reference types can be e.g. cart, category, channel, customer, and payment.

All Rights Reserved © 2017 24

Reference Expansion
/products/<example-product-id>

reference

All Rights Reserved © 2017 25

Reference Expansion
/products/<example-product-id>?expand=productType

Expanded reference

reference

All Rights Reserved © 2017 26

Resource Identifier

Reference by Id or Key.

Id à Platform generated.

Key à Selected manually,

Not all resources support key currently. Examples: products, product types.

All Rights Reserved © 2017 27

Money

A JSON object.

{
”currencyCode": ”EUR",
”centAmount": 4200
}

Currency code is compliant to ISO 4217.

Amount in cent: e.g. 4200 à 42 Euros.

All Rights Reserved © 2017 28

DateTime

A JSON string.

"2001-09-11T14:00:00.000Z"

T separates date from time.

Z is zero hour offset.

All Rights Reserved © 2017 29

Address

A JSON string.

id
title
salutation
firstName
lastName
streetName
streetNumber
postalCode
region
state
country*
…

All Rights Reserved © 2017 30

API Errors

All Rights Reserved © 2017 31

API Errors

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

500 Internal Server Error

503 Service Unavailable

All Rights Reserved © 2017 32

API Errors – General Structure

{
"statusCode": XXX, // e.g. 400
"message": "First error message",
"errors": [
{
"code":"SomeErrorCode",
"message": "First error message”
},
{
"code":"SomeErrorCode",
"message": "Second error message”
}
]
}

All Rights Reserved © 2017 33

API Errors

400 Bad Request

• Most common error.

• May occur with GET, POST, and DELETE methods.

• Request failed due to bad input.

• Error codes:
• InvalidInput
• InvalidOperation
• InvalidField
• RequiredField
• DuplicateField

All Rights Reserved © 2017 34

API Errors
{
"statusCode": 409,
"message": "Version mismatch. Concurrent modification.",
"errors": [
{
"code": "ConcurrentModification",
"message": "Version mismatch. Concurrent modification.",
"currentVersion": 2
}
]

409 Conflict
}

• Targeted resource has been modified.

• currentVersion is required.

• May occur with POST and DELETE methods.

All Rights Reserved © 2017 35