BEST PRACTICES FOR DESIGNING SUPERIOR
RESTFUL APIS
Rohit BhardwajPrincipal Cloud Engineerrbhardwajkronoscom
Twitter rbhardwaj1
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
WEB API
RESTFUL APISbull REpresentational State Transfer
bull Separation of Client and Server
bull Server Requests are Stateless
bull Cacheable Requests
bull Uniform interface
RESOURCE BASED ARCHITECTURE
HYPERMEDIA
httpwwwjaywaycomwp-contentuploads201210hypermedia-applicationpng
DESIGNING APIS
REST-FUL URIS AND NON-REST-FUL URIS
bull adminupdatebookjspbook=5
bull bookviewjspbook=5
bull bookandreviewsjspbook=5
NOUNS ARE GREAT VERBS ARE BAD
WHAT IS SOLUTIONbull Prefer Plurals
bull httpapiCustomers
bull httpapiEmployees
bull httpapiStates
bull httpapiOrders
IDENTIFIERS KEY
bull httpapiCustomers978
bull httpapiEmployeesemp123
bull httpapiStatesMA
bull httpapiOrders234
WHERE DOES VERBS GO
WHERE DOES VERBS GO
WHAT SHOULD YOU RETURN
RESOURCE
STATUS CODES
HOW TO SATISFY ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiEmployeesemp123Address
bull httpapiStatesMACities
bull httpapiOrders234Details
RETURN SAME OBJECT
bull httpapiStatesMACities
bull httpapiCities
SAME OBJECT MULTI ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiCustomers978Shipments
bull httpapiCustomers978Invoices
WHAT IF YOU HAVE COMPLEX ASSOCIATION
bull httpapiCustomersstate=MA
bull httpapiCustomersstate=MAampCity=Chelmsford
HOW TO FORMAT RESULTSbull Use content Negotiation
bull Accept header
GET apicustomers987 HTTP11
Accept applicationjson textxml
Host localhost9876
MIME TYPES
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
WEB API
RESTFUL APISbull REpresentational State Transfer
bull Separation of Client and Server
bull Server Requests are Stateless
bull Cacheable Requests
bull Uniform interface
RESOURCE BASED ARCHITECTURE
HYPERMEDIA
httpwwwjaywaycomwp-contentuploads201210hypermedia-applicationpng
DESIGNING APIS
REST-FUL URIS AND NON-REST-FUL URIS
bull adminupdatebookjspbook=5
bull bookviewjspbook=5
bull bookandreviewsjspbook=5
NOUNS ARE GREAT VERBS ARE BAD
WHAT IS SOLUTIONbull Prefer Plurals
bull httpapiCustomers
bull httpapiEmployees
bull httpapiStates
bull httpapiOrders
IDENTIFIERS KEY
bull httpapiCustomers978
bull httpapiEmployeesemp123
bull httpapiStatesMA
bull httpapiOrders234
WHERE DOES VERBS GO
WHERE DOES VERBS GO
WHAT SHOULD YOU RETURN
RESOURCE
STATUS CODES
HOW TO SATISFY ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiEmployeesemp123Address
bull httpapiStatesMACities
bull httpapiOrders234Details
RETURN SAME OBJECT
bull httpapiStatesMACities
bull httpapiCities
SAME OBJECT MULTI ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiCustomers978Shipments
bull httpapiCustomers978Invoices
WHAT IF YOU HAVE COMPLEX ASSOCIATION
bull httpapiCustomersstate=MA
bull httpapiCustomersstate=MAampCity=Chelmsford
HOW TO FORMAT RESULTSbull Use content Negotiation
bull Accept header
GET apicustomers987 HTTP11
Accept applicationjson textxml
Host localhost9876
MIME TYPES
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
WEB API
RESTFUL APISbull REpresentational State Transfer
bull Separation of Client and Server
bull Server Requests are Stateless
bull Cacheable Requests
bull Uniform interface
RESOURCE BASED ARCHITECTURE
HYPERMEDIA
httpwwwjaywaycomwp-contentuploads201210hypermedia-applicationpng
DESIGNING APIS
REST-FUL URIS AND NON-REST-FUL URIS
bull adminupdatebookjspbook=5
bull bookviewjspbook=5
bull bookandreviewsjspbook=5
NOUNS ARE GREAT VERBS ARE BAD
WHAT IS SOLUTIONbull Prefer Plurals
bull httpapiCustomers
bull httpapiEmployees
bull httpapiStates
bull httpapiOrders
IDENTIFIERS KEY
bull httpapiCustomers978
bull httpapiEmployeesemp123
bull httpapiStatesMA
bull httpapiOrders234
WHERE DOES VERBS GO
WHERE DOES VERBS GO
WHAT SHOULD YOU RETURN
RESOURCE
STATUS CODES
HOW TO SATISFY ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiEmployeesemp123Address
bull httpapiStatesMACities
bull httpapiOrders234Details
RETURN SAME OBJECT
bull httpapiStatesMACities
bull httpapiCities
SAME OBJECT MULTI ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiCustomers978Shipments
bull httpapiCustomers978Invoices
WHAT IF YOU HAVE COMPLEX ASSOCIATION
bull httpapiCustomersstate=MA
bull httpapiCustomersstate=MAampCity=Chelmsford
HOW TO FORMAT RESULTSbull Use content Negotiation
bull Accept header
GET apicustomers987 HTTP11
Accept applicationjson textxml
Host localhost9876
MIME TYPES
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
RESTFUL APISbull REpresentational State Transfer
bull Separation of Client and Server
bull Server Requests are Stateless
bull Cacheable Requests
bull Uniform interface
RESOURCE BASED ARCHITECTURE
HYPERMEDIA
httpwwwjaywaycomwp-contentuploads201210hypermedia-applicationpng
DESIGNING APIS
REST-FUL URIS AND NON-REST-FUL URIS
bull adminupdatebookjspbook=5
bull bookviewjspbook=5
bull bookandreviewsjspbook=5
NOUNS ARE GREAT VERBS ARE BAD
WHAT IS SOLUTIONbull Prefer Plurals
bull httpapiCustomers
bull httpapiEmployees
bull httpapiStates
bull httpapiOrders
IDENTIFIERS KEY
bull httpapiCustomers978
bull httpapiEmployeesemp123
bull httpapiStatesMA
bull httpapiOrders234
WHERE DOES VERBS GO
WHERE DOES VERBS GO
WHAT SHOULD YOU RETURN
RESOURCE
STATUS CODES
HOW TO SATISFY ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiEmployeesemp123Address
bull httpapiStatesMACities
bull httpapiOrders234Details
RETURN SAME OBJECT
bull httpapiStatesMACities
bull httpapiCities
SAME OBJECT MULTI ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiCustomers978Shipments
bull httpapiCustomers978Invoices
WHAT IF YOU HAVE COMPLEX ASSOCIATION
bull httpapiCustomersstate=MA
bull httpapiCustomersstate=MAampCity=Chelmsford
HOW TO FORMAT RESULTSbull Use content Negotiation
bull Accept header
GET apicustomers987 HTTP11
Accept applicationjson textxml
Host localhost9876
MIME TYPES
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
RESOURCE BASED ARCHITECTURE
HYPERMEDIA
httpwwwjaywaycomwp-contentuploads201210hypermedia-applicationpng
DESIGNING APIS
REST-FUL URIS AND NON-REST-FUL URIS
bull adminupdatebookjspbook=5
bull bookviewjspbook=5
bull bookandreviewsjspbook=5
NOUNS ARE GREAT VERBS ARE BAD
WHAT IS SOLUTIONbull Prefer Plurals
bull httpapiCustomers
bull httpapiEmployees
bull httpapiStates
bull httpapiOrders
IDENTIFIERS KEY
bull httpapiCustomers978
bull httpapiEmployeesemp123
bull httpapiStatesMA
bull httpapiOrders234
WHERE DOES VERBS GO
WHERE DOES VERBS GO
WHAT SHOULD YOU RETURN
RESOURCE
STATUS CODES
HOW TO SATISFY ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiEmployeesemp123Address
bull httpapiStatesMACities
bull httpapiOrders234Details
RETURN SAME OBJECT
bull httpapiStatesMACities
bull httpapiCities
SAME OBJECT MULTI ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiCustomers978Shipments
bull httpapiCustomers978Invoices
WHAT IF YOU HAVE COMPLEX ASSOCIATION
bull httpapiCustomersstate=MA
bull httpapiCustomersstate=MAampCity=Chelmsford
HOW TO FORMAT RESULTSbull Use content Negotiation
bull Accept header
GET apicustomers987 HTTP11
Accept applicationjson textxml
Host localhost9876
MIME TYPES
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
HYPERMEDIA
httpwwwjaywaycomwp-contentuploads201210hypermedia-applicationpng
DESIGNING APIS
REST-FUL URIS AND NON-REST-FUL URIS
bull adminupdatebookjspbook=5
bull bookviewjspbook=5
bull bookandreviewsjspbook=5
NOUNS ARE GREAT VERBS ARE BAD
WHAT IS SOLUTIONbull Prefer Plurals
bull httpapiCustomers
bull httpapiEmployees
bull httpapiStates
bull httpapiOrders
IDENTIFIERS KEY
bull httpapiCustomers978
bull httpapiEmployeesemp123
bull httpapiStatesMA
bull httpapiOrders234
WHERE DOES VERBS GO
WHERE DOES VERBS GO
WHAT SHOULD YOU RETURN
RESOURCE
STATUS CODES
HOW TO SATISFY ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiEmployeesemp123Address
bull httpapiStatesMACities
bull httpapiOrders234Details
RETURN SAME OBJECT
bull httpapiStatesMACities
bull httpapiCities
SAME OBJECT MULTI ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiCustomers978Shipments
bull httpapiCustomers978Invoices
WHAT IF YOU HAVE COMPLEX ASSOCIATION
bull httpapiCustomersstate=MA
bull httpapiCustomersstate=MAampCity=Chelmsford
HOW TO FORMAT RESULTSbull Use content Negotiation
bull Accept header
GET apicustomers987 HTTP11
Accept applicationjson textxml
Host localhost9876
MIME TYPES
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
httpwwwjaywaycomwp-contentuploads201210hypermedia-applicationpng
DESIGNING APIS
REST-FUL URIS AND NON-REST-FUL URIS
bull adminupdatebookjspbook=5
bull bookviewjspbook=5
bull bookandreviewsjspbook=5
NOUNS ARE GREAT VERBS ARE BAD
WHAT IS SOLUTIONbull Prefer Plurals
bull httpapiCustomers
bull httpapiEmployees
bull httpapiStates
bull httpapiOrders
IDENTIFIERS KEY
bull httpapiCustomers978
bull httpapiEmployeesemp123
bull httpapiStatesMA
bull httpapiOrders234
WHERE DOES VERBS GO
WHERE DOES VERBS GO
WHAT SHOULD YOU RETURN
RESOURCE
STATUS CODES
HOW TO SATISFY ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiEmployeesemp123Address
bull httpapiStatesMACities
bull httpapiOrders234Details
RETURN SAME OBJECT
bull httpapiStatesMACities
bull httpapiCities
SAME OBJECT MULTI ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiCustomers978Shipments
bull httpapiCustomers978Invoices
WHAT IF YOU HAVE COMPLEX ASSOCIATION
bull httpapiCustomersstate=MA
bull httpapiCustomersstate=MAampCity=Chelmsford
HOW TO FORMAT RESULTSbull Use content Negotiation
bull Accept header
GET apicustomers987 HTTP11
Accept applicationjson textxml
Host localhost9876
MIME TYPES
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
DESIGNING APIS
REST-FUL URIS AND NON-REST-FUL URIS
bull adminupdatebookjspbook=5
bull bookviewjspbook=5
bull bookandreviewsjspbook=5
NOUNS ARE GREAT VERBS ARE BAD
WHAT IS SOLUTIONbull Prefer Plurals
bull httpapiCustomers
bull httpapiEmployees
bull httpapiStates
bull httpapiOrders
IDENTIFIERS KEY
bull httpapiCustomers978
bull httpapiEmployeesemp123
bull httpapiStatesMA
bull httpapiOrders234
WHERE DOES VERBS GO
WHERE DOES VERBS GO
WHAT SHOULD YOU RETURN
RESOURCE
STATUS CODES
HOW TO SATISFY ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiEmployeesemp123Address
bull httpapiStatesMACities
bull httpapiOrders234Details
RETURN SAME OBJECT
bull httpapiStatesMACities
bull httpapiCities
SAME OBJECT MULTI ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiCustomers978Shipments
bull httpapiCustomers978Invoices
WHAT IF YOU HAVE COMPLEX ASSOCIATION
bull httpapiCustomersstate=MA
bull httpapiCustomersstate=MAampCity=Chelmsford
HOW TO FORMAT RESULTSbull Use content Negotiation
bull Accept header
GET apicustomers987 HTTP11
Accept applicationjson textxml
Host localhost9876
MIME TYPES
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
REST-FUL URIS AND NON-REST-FUL URIS
bull adminupdatebookjspbook=5
bull bookviewjspbook=5
bull bookandreviewsjspbook=5
NOUNS ARE GREAT VERBS ARE BAD
WHAT IS SOLUTIONbull Prefer Plurals
bull httpapiCustomers
bull httpapiEmployees
bull httpapiStates
bull httpapiOrders
IDENTIFIERS KEY
bull httpapiCustomers978
bull httpapiEmployeesemp123
bull httpapiStatesMA
bull httpapiOrders234
WHERE DOES VERBS GO
WHERE DOES VERBS GO
WHAT SHOULD YOU RETURN
RESOURCE
STATUS CODES
HOW TO SATISFY ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiEmployeesemp123Address
bull httpapiStatesMACities
bull httpapiOrders234Details
RETURN SAME OBJECT
bull httpapiStatesMACities
bull httpapiCities
SAME OBJECT MULTI ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiCustomers978Shipments
bull httpapiCustomers978Invoices
WHAT IF YOU HAVE COMPLEX ASSOCIATION
bull httpapiCustomersstate=MA
bull httpapiCustomersstate=MAampCity=Chelmsford
HOW TO FORMAT RESULTSbull Use content Negotiation
bull Accept header
GET apicustomers987 HTTP11
Accept applicationjson textxml
Host localhost9876
MIME TYPES
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
NOUNS ARE GREAT VERBS ARE BAD
WHAT IS SOLUTIONbull Prefer Plurals
bull httpapiCustomers
bull httpapiEmployees
bull httpapiStates
bull httpapiOrders
IDENTIFIERS KEY
bull httpapiCustomers978
bull httpapiEmployeesemp123
bull httpapiStatesMA
bull httpapiOrders234
WHERE DOES VERBS GO
WHERE DOES VERBS GO
WHAT SHOULD YOU RETURN
RESOURCE
STATUS CODES
HOW TO SATISFY ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiEmployeesemp123Address
bull httpapiStatesMACities
bull httpapiOrders234Details
RETURN SAME OBJECT
bull httpapiStatesMACities
bull httpapiCities
SAME OBJECT MULTI ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiCustomers978Shipments
bull httpapiCustomers978Invoices
WHAT IF YOU HAVE COMPLEX ASSOCIATION
bull httpapiCustomersstate=MA
bull httpapiCustomersstate=MAampCity=Chelmsford
HOW TO FORMAT RESULTSbull Use content Negotiation
bull Accept header
GET apicustomers987 HTTP11
Accept applicationjson textxml
Host localhost9876
MIME TYPES
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
WHAT IS SOLUTIONbull Prefer Plurals
bull httpapiCustomers
bull httpapiEmployees
bull httpapiStates
bull httpapiOrders
IDENTIFIERS KEY
bull httpapiCustomers978
bull httpapiEmployeesemp123
bull httpapiStatesMA
bull httpapiOrders234
WHERE DOES VERBS GO
WHERE DOES VERBS GO
WHAT SHOULD YOU RETURN
RESOURCE
STATUS CODES
HOW TO SATISFY ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiEmployeesemp123Address
bull httpapiStatesMACities
bull httpapiOrders234Details
RETURN SAME OBJECT
bull httpapiStatesMACities
bull httpapiCities
SAME OBJECT MULTI ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiCustomers978Shipments
bull httpapiCustomers978Invoices
WHAT IF YOU HAVE COMPLEX ASSOCIATION
bull httpapiCustomersstate=MA
bull httpapiCustomersstate=MAampCity=Chelmsford
HOW TO FORMAT RESULTSbull Use content Negotiation
bull Accept header
GET apicustomers987 HTTP11
Accept applicationjson textxml
Host localhost9876
MIME TYPES
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
IDENTIFIERS KEY
bull httpapiCustomers978
bull httpapiEmployeesemp123
bull httpapiStatesMA
bull httpapiOrders234
WHERE DOES VERBS GO
WHERE DOES VERBS GO
WHAT SHOULD YOU RETURN
RESOURCE
STATUS CODES
HOW TO SATISFY ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiEmployeesemp123Address
bull httpapiStatesMACities
bull httpapiOrders234Details
RETURN SAME OBJECT
bull httpapiStatesMACities
bull httpapiCities
SAME OBJECT MULTI ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiCustomers978Shipments
bull httpapiCustomers978Invoices
WHAT IF YOU HAVE COMPLEX ASSOCIATION
bull httpapiCustomersstate=MA
bull httpapiCustomersstate=MAampCity=Chelmsford
HOW TO FORMAT RESULTSbull Use content Negotiation
bull Accept header
GET apicustomers987 HTTP11
Accept applicationjson textxml
Host localhost9876
MIME TYPES
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
WHERE DOES VERBS GO
WHERE DOES VERBS GO
WHAT SHOULD YOU RETURN
RESOURCE
STATUS CODES
HOW TO SATISFY ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiEmployeesemp123Address
bull httpapiStatesMACities
bull httpapiOrders234Details
RETURN SAME OBJECT
bull httpapiStatesMACities
bull httpapiCities
SAME OBJECT MULTI ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiCustomers978Shipments
bull httpapiCustomers978Invoices
WHAT IF YOU HAVE COMPLEX ASSOCIATION
bull httpapiCustomersstate=MA
bull httpapiCustomersstate=MAampCity=Chelmsford
HOW TO FORMAT RESULTSbull Use content Negotiation
bull Accept header
GET apicustomers987 HTTP11
Accept applicationjson textxml
Host localhost9876
MIME TYPES
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
WHERE DOES VERBS GO
WHAT SHOULD YOU RETURN
RESOURCE
STATUS CODES
HOW TO SATISFY ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiEmployeesemp123Address
bull httpapiStatesMACities
bull httpapiOrders234Details
RETURN SAME OBJECT
bull httpapiStatesMACities
bull httpapiCities
SAME OBJECT MULTI ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiCustomers978Shipments
bull httpapiCustomers978Invoices
WHAT IF YOU HAVE COMPLEX ASSOCIATION
bull httpapiCustomersstate=MA
bull httpapiCustomersstate=MAampCity=Chelmsford
HOW TO FORMAT RESULTSbull Use content Negotiation
bull Accept header
GET apicustomers987 HTTP11
Accept applicationjson textxml
Host localhost9876
MIME TYPES
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
WHAT SHOULD YOU RETURN
RESOURCE
STATUS CODES
HOW TO SATISFY ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiEmployeesemp123Address
bull httpapiStatesMACities
bull httpapiOrders234Details
RETURN SAME OBJECT
bull httpapiStatesMACities
bull httpapiCities
SAME OBJECT MULTI ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiCustomers978Shipments
bull httpapiCustomers978Invoices
WHAT IF YOU HAVE COMPLEX ASSOCIATION
bull httpapiCustomersstate=MA
bull httpapiCustomersstate=MAampCity=Chelmsford
HOW TO FORMAT RESULTSbull Use content Negotiation
bull Accept header
GET apicustomers987 HTTP11
Accept applicationjson textxml
Host localhost9876
MIME TYPES
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
RESOURCE
STATUS CODES
HOW TO SATISFY ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiEmployeesemp123Address
bull httpapiStatesMACities
bull httpapiOrders234Details
RETURN SAME OBJECT
bull httpapiStatesMACities
bull httpapiCities
SAME OBJECT MULTI ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiCustomers978Shipments
bull httpapiCustomers978Invoices
WHAT IF YOU HAVE COMPLEX ASSOCIATION
bull httpapiCustomersstate=MA
bull httpapiCustomersstate=MAampCity=Chelmsford
HOW TO FORMAT RESULTSbull Use content Negotiation
bull Accept header
GET apicustomers987 HTTP11
Accept applicationjson textxml
Host localhost9876
MIME TYPES
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
STATUS CODES
HOW TO SATISFY ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiEmployeesemp123Address
bull httpapiStatesMACities
bull httpapiOrders234Details
RETURN SAME OBJECT
bull httpapiStatesMACities
bull httpapiCities
SAME OBJECT MULTI ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiCustomers978Shipments
bull httpapiCustomers978Invoices
WHAT IF YOU HAVE COMPLEX ASSOCIATION
bull httpapiCustomersstate=MA
bull httpapiCustomersstate=MAampCity=Chelmsford
HOW TO FORMAT RESULTSbull Use content Negotiation
bull Accept header
GET apicustomers987 HTTP11
Accept applicationjson textxml
Host localhost9876
MIME TYPES
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
HOW TO SATISFY ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiEmployeesemp123Address
bull httpapiStatesMACities
bull httpapiOrders234Details
RETURN SAME OBJECT
bull httpapiStatesMACities
bull httpapiCities
SAME OBJECT MULTI ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiCustomers978Shipments
bull httpapiCustomers978Invoices
WHAT IF YOU HAVE COMPLEX ASSOCIATION
bull httpapiCustomersstate=MA
bull httpapiCustomersstate=MAampCity=Chelmsford
HOW TO FORMAT RESULTSbull Use content Negotiation
bull Accept header
GET apicustomers987 HTTP11
Accept applicationjson textxml
Host localhost9876
MIME TYPES
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
RETURN SAME OBJECT
bull httpapiStatesMACities
bull httpapiCities
SAME OBJECT MULTI ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiCustomers978Shipments
bull httpapiCustomers978Invoices
WHAT IF YOU HAVE COMPLEX ASSOCIATION
bull httpapiCustomersstate=MA
bull httpapiCustomersstate=MAampCity=Chelmsford
HOW TO FORMAT RESULTSbull Use content Negotiation
bull Accept header
GET apicustomers987 HTTP11
Accept applicationjson textxml
Host localhost9876
MIME TYPES
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
SAME OBJECT MULTI ASSOCIATIONS
bull httpapiCustomers978Orders
bull httpapiCustomers978Shipments
bull httpapiCustomers978Invoices
WHAT IF YOU HAVE COMPLEX ASSOCIATION
bull httpapiCustomersstate=MA
bull httpapiCustomersstate=MAampCity=Chelmsford
HOW TO FORMAT RESULTSbull Use content Negotiation
bull Accept header
GET apicustomers987 HTTP11
Accept applicationjson textxml
Host localhost9876
MIME TYPES
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
WHAT IF YOU HAVE COMPLEX ASSOCIATION
bull httpapiCustomersstate=MA
bull httpapiCustomersstate=MAampCity=Chelmsford
HOW TO FORMAT RESULTSbull Use content Negotiation
bull Accept header
GET apicustomers987 HTTP11
Accept applicationjson textxml
Host localhost9876
MIME TYPES
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
HOW TO FORMAT RESULTSbull Use content Negotiation
bull Accept header
GET apicustomers987 HTTP11
Accept applicationjson textxml
Host localhost9876
MIME TYPES
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
MIME TYPES
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
FORMATING
bull httpapiCustomersformat=json
bull httpapiCustomersjson
bull httpapiCustomers format=jsonpampcallback=foo
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
JSON EXAMPLE13 13 13 13 13 13 ldquoidrdquo13 13 97813 13 13 13 13 13 firstName13 John13 13 13 13 13 13 lastName13 Smith13 13 13 13 13 13 age13 4513 13 13 13 13 13 address13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 streetAddress13 ldquo2113 Chelmsford13 Street13 13 13 13 13 13 13 13 13 13 city13 New13 York13 13 13 13 13 13 13 13 13 13 state13 NY13 13 13 13 13 13 13 13 13 13 postalCode13 1029313 13 13 13 13 13 13 13 13 13 13 13 phoneNumber13 13 13 13 13 13 [13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 home13 13 13 13 13 13 13 13 13 13 13 13 number13 98713 555-shy‐123413 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 type13 fax13 13 13 13 13 13 13 13 13 13 13 13 number13 93813 555-shy‐373313 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 ]13 13
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
MEMBER NAMES
bull Use camelCasing - Objects
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
HANDLING ERRORS
bull Learn writing code through errors
bull Test Driven Development
bull Troubleshooting and resolving issues
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
ERROR HANDLING APPROACH 1
Facebook13 HTTP Status Code 200 type OauthException message(803) Some of the aliases you requested do not exist foobar Twilio13 HTTP Status Code 401 status 401 messageAuthenticatecode 20003 ldquomore info httpwwwtwiliocomdocserrors20003 SimpleGeo13 HTTP Status Code 401 code 401 message Authentication Required
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
BE VERBOSE AND USE PLAIN LANGUAGE DESCRIPTIONS
bull developerMessage Verbose plain language description of the problem for the app developer with hints about how to fix it userMessagePass this message on to the app user if needed errorCode 12345 more infordquo httpdevteachdogrestcomerrors12345
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
DESIGNING COLLECTIONS ldquonumberOfResultsrdquo 6 ldquoretultsrdquo [ ldquoidrdquo 978 firstName John lastName Smith age 45 address streetAddress ldquo21 Chelmsford Street city New York state NY postalCode 10293 phoneNumber [ type home number 987 555-1234 type fax number 938 555-3733 helliphelliphelliphelliphellip ]
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Strong and Weak CachingHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag 10c24bc-4ab-457wer1fContent-Length 12195
GET iyahoogif HTTP11Host usyimgcomIf-Modified-Since Tue 12 Dec 2015 030359 GMTIf-None-Match 10c24bc-4ab-457e1c1fHTTP11 304 Not Modified
Use 304 to indicate object not modified
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
ENTITY TAGS (ETAGS)
bull Header to support smart server caching
bull Weak Caching Objects are semantically sameHTTP11 200 OKLast-Modified Tue 12 Dec 2015 030359 GMTETag Wldquo10c24bc-4ab-457wer1fContent-Length 12195
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
PAGING TO RETURN COLLECTIONS
bull Prevent to return huge amount of data
bull Large result sets performance
bull Query String parameter to narrow down
bull GET customersoffset=10amplimit=5
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
FILTERING
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
FILTERING
bull GET customerv1userordersfrom=01122016ampto=01122016ampsort=ascendingampby=hellipampindex=0ampcount=20
bull The equivalent long form is
bull GET customerv1userorderswhere=rdquofrom=01122016 and to=01122016rdquoampsort=ascendingampby=hellipamp index=0ampcount=20
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
BATCH CRUD OPERATIONS
bull multi_create
bull multi_read
bull multi_update
bull multi_delete
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
I18NL10N
bull Language
bull Support ISO 639 Language codes
bull Currency
bull ISO 4217 Currency codes
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
I18NL10N
bull Numbers Support Decimal XML Schema
bull +2 -12345 034 0
bull Floats and doubles IEEE 754-1985
bull -1E4 123443233E10 1278e-3 13 -0 0
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
I18NL10N bull Datetime ISO-8601 standard
bull Date YYYY-MM-DD -gt 2011-12-03
bull Date and time YYYY-MM-DDrsquoTrsquoHHMMSS -gt 2011-12-03T101530
bull Time HHMMSS -gt 101530
bull
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
Chatty APIs Bandwidth Aware
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
Reduce chattiness
httptechblognetflixcom201301optimizing-netflix-apihtml
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
PAGING
bull totalNumResults 9999nextPage httpapicustomerspage=5 prevPage httpapicustomerspage=1 results []
bull
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
PARTIAL ITEMSbull Query string to return less
bull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
bull httpsdevelopersgooglecomdrivev3webperformancepartial-response
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
APIbull httpswwwgoogleapiscomdemov1key=YOUR-API-KEY
kind demo items [ title First title comment First comment characteristics length short accuracy high followers [Jo Will] status active title Second title comment Second comment characteristics length long accuracy medium followers [ ] status pending ]
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
PARTIAL ITEMSbull httpswwwgoogleapiscomdemov1key=YOUR-API-
KEYampfields=kinditems(titlecharacteristicslength)200 OK
kind demo items [ title First title characteristics length short title Second title characteristics length long ]
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
NON RESOURCE APISbull get support only
bull Should be functional API
bull httpapicalculatePricestate=MAamptotal=6295
bull httpapipingServerisNotify=true
bull httpapiweatherForecastisSummary=trueampstate=ldquoMArdquo
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
SUMMARYbull Do not surprise users
bull Follow patterns available
bull Caching and use Etags
bull Use of Partial items
bull Non Resource APIs
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
VERSIONING REST APIS
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
WHY VERSIONINGbull Publishing an API is not a trivial move
bull UsersCustomers rely on the API not changing
bull But requirements will change
bull Need a way to evolve the API without breaking existing clients
bull API Versioning isnt Product Versioning Donrsquot tie them together
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
httpzentofitnesscomwp-contentuploads201107breaking-chainsSjpg
bull Thy Shall not break existing Customers
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
EXAMPLESbull Uri Path
bull Tumbler
bull httpapitumblrcomv2user
bull Uri Parameter
bull Netflix
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull Content Negotiation
bull GitHub API
bull ContentTypeapplicationvndgithub1param+json
bull Request Header
bull Azure
bull x-ms-version2011-08-18
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
VERSIONING IN THE URI PATH bull Using Part of Your Path to Version
bull Allows you to drastically change the API
bull Everything below the version is open to change
bull Twitter
bull httpapitwittercom1usersshownoradioxml
bull Atlassian
bull httphostportcontextrestupm1plugina-plugin-key
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
URI PATH
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
VERSIONING IN THE URI PATH bull Pro(s)
bull Simple to segregate old APIs for backwards compatibility
bull Con(s)
bull Requires lots of client changes as you version Eg version has to change in every client
bull Increases the size of the URI surface area you have to support
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
VERSIONING IN THE URI PARAMETERS
bull httpapinetflixcomcatalogtitlesseries70023522v=15
bull httpapiEmployees
bull httpapiEmployeesv=31
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
VERSIONING IN THE URI PARAMETERS
bull Pro(s)
bull Without version users always get latest version of API
bull Little client change as versions mature
bull Con(s)
bull Can surprise developers with unintended changes
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
HYPERMEDIA CONTROL
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
VERSIONING WITH CONTENT NEGOTIATION
bull GET apiemployee978HOST httpAccept applicationmyappv3employee
bull GET apiemployee123HOST httpAccept applicationmyappv3employeejson
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
VENDOR TYPE VERSION THE REQUEST TYPE
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v1+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v1+xml
ltcustomergt
ltnamegtNeil Armstrongltnamegt
ltcustomergthttpthereisnorightwayblogspotcom201102versioning-and-types-in-resthttp-apihtml
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
NEWER CLIENTS MAKE A DIFFERENT CALL
===gt
GET customer123 HTTP11
Accept applicationvndcompanymyappcustomer-v2+xml
lt===
HTTP11 200 OK
Content-Type applicationvndcompanymyappcustomer-v2+xml
ltcustomergt
ltfirstNameltNeilgtfirstNamegt
ltlastNameltArmstronggtlastNamegt
ltsalutationgtMrltsalutationgt
ltcustomergt
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
VERSIONING WITH CONTENT NEGOTIATION
bull Pro(s)
bull Packages API and Resource Versioning in one
bull Removes versioning from API so clients dont have to change
bull Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
bull Can encourage increased versioning which causes more code churning
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
VERSIONING WITH CUSTOM HEADER
GET apicustomer123
HOST http
x-MyApp-Version 21
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
ADDING DATE
GET apicustomer123
HOST http
x-MyApp-Version 2013-08-13
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
VERSIONING WITH CUSTOM HEADER
bull Pro(s)
bull Separates Versioning from API call signatures
bull Not tied to resource versioning (eg Content Type) Con(s)
bull Adds complexity - adding headers isnt easy on all platforms
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
WHICH ONE TO CHOOSEbull There is no easy answer
bull Versioning with Content Negotiation and Custom Headers are popular now
bull Versioning with URI Components are more common
bull These are easier to implement
bull But you should version from the first release of your API
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
bull YOU MUST VERSION API
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
API SECURITY
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
SECURITY APISbull Threats
bull Protecting APIs
bull Authentication
bull API Keys How they work
bull User Authentication and Authorization
bull SAML
bull Understanding OAuth
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
WHY NEED TO SECURE
US laws and Regulations
International laws and regulation
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
Privacy KPMG Data life cycle
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
Data Security lifecycle
wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
WHY PROTECT APIS
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
bull Server-to-Server Authentication
bull API Keys and Shared Secrets
bull User Proxy Authentication
bull OAuth
bull Direct User Authentication
bull Cookies or token
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
bull Credential
bull A fact that describe an identity
bull Authentication
bull Validate a set of credentials to identify an entity (whether virtual or actual)
bull Authorization
bull Verification that an entity has rights to access a resource or action
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
Confidentiality Symmetric Encryption Efficient
Data Accountability and Trust Act 2006
httpcodegooglecompjscryptolibhttpskeybaseiotriplesec
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
httpskeybaseiotriplesec
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
Confidentiality Asymmetric Encryption
httpwwwsecurecottagecomdemorsa2html httpsupportpersitscomencryptdemo_textasp httpsupportpersitscompdfdemo_encryptaspx
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
AUTHENTICATING USERS
bull Within system
bull OAuth
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
OAUTH
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
Open Authentication (OAuth)
httpbrentertainmentcomoauth2
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
DOCUMENTATION
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
OAUTH AND SWAGGER DEMO
httppetstoreswaggerio
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
JSON WEB TOKENS
Compact and self-contained way for securely transmitting information between parties as a JSON object
httpsjwtiointroduction
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
httpmicroservicesiopatternsapigatewayhtml
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
API
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
HYPERMEDIA LINKS IN API
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
JSON
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
RETURNING MORE ACTIONS
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
HAL HYPERTEXT APPLICATION LANGUAGE
bull HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API
Amazon Chooses HAL Media Type for AppStream APIhttpwwwinfoqcomnews201403amazon-hal-appstream
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
httpstatelesscohal_specificationhtmlhttphaltalkherokuappcomexplorerbrowserhtml
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
httpmartinfowlercomarticlesconsumerDrivenContractshtml
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
httptechblognewsweavercomwhy-should-you-use-consumer-driven-contracts-for-microservices-integration-tests
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
API MANAGEMENT
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
TEST REST APIS
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
POSTMAN DEMO
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing
DESIGNING RESTFUL APISbull RESTful APIs
bull Hypermedia
bull Principles for designing APIs
bull SAML and OAuth
bull Customer driven contract
bull API testing