API Design Best Practices & Tech Talk : API Craft Meetup @ Apigee

47
APIs Tech Talk API Craft Meetup – 20 June 2015

Transcript of API Design Best Practices & Tech Talk : API Craft Meetup @ Apigee

APIs Tech TalkAPI Craft Meetup – 20 June

2015

Today’s speaker

Anil [email protected]

API Craft - Meetup

• API Design

• Various API Platform Analysis – Use Cases

• Building API Server as a tier

• API Server -- Mobile App

• Usergrid

• API Studio

• Apigee 127

API Craft - Meetup• Why APIs ?

• API Design Best Practices

• Importance of API Server

• Usergrid – Removing a server side layer

• Introduction to Apigee 127, Hands On

• Introduction to Usergrid, Hands On

• App Contest - Hackathon

• Code Sprints – Open Source Contribution

• Why (REST) APIs ?

• API Eco System

• Web API Design

• Q & A

Today’s Overview

Why ( REST ) APIs ?

8

APIs

?

9

APIs

Web

Point of Sale

Partner

App, API, Analytics Infrastructure

Mobile

ESB, SOA,App Servers,Databases

Backend Services

API Eco System

11

DIGITAL VALUE CHAIN

12

Digital requires the right foundation

API and data

Reporting andmonitoring Monetization

Globaldeployment

Security

OnboardingAPIdocumentation

Developerauthentication

Mobileoptimization

Trafficmanagement Partner

customization

Transformation

Versioning

Predictive

analytics

Data

API Tools & Softwares

14

APIs…

Web API Design

REST APIs

• Architecture Style – Not a Standard

• Performance, Scalability, Simplicity

• Typically, Communicate over HTTP

• Using HTTP Verbs– GET– POST– DELETE– PUT

17

Nouns are Good; Verbs are bad

Keep Verbs out of your Base URLs

Keep Verbs out of your Base URLs

20

Singular Nouns or Plural Nouns ?

Singular Nouns or Plural Nouns ?

• Foursquare – /checkins

• GroupOn– /deals

• Zappos– /Product

Singular Nouns or Plural Nouns ?

• Avoid Mixed Model

• Consistent

• Prefer plural names– Reads more Easily– Intuitive

23

Concrete Names are better than abstract…

Concrete Names are better than abstract…

• Abstractions is Not Always Meaningful

• Depends on your scenario

• Keep Number of Resources between 12 - 24

Associations

• /resource/identifier/resource

Complexity – Put it behind the ?

• States that can be updated, changed, queried

• Attributes associated with resource

Handling Errors…

• Important piece of puzzle

• Other Side of the API is a black box

Handling Errors – Best Practices

• Granular Error Messages

• Link to Documentation

• Aligning Errors with Status Codes

• Verbose as Possible

Handling Errors – Status Codes

• Start With 3 Codes– 200 – OK – Everything is Fine– 400 – BAD REQUEST – Something wrong with App– 500 – INTERNAL SERVER APP – Something wrong

with Server

• Not more than 8 Codes– 201 , 304, 404, 401, 403

Handling Errors – Status Codes

• Start With 3 Codes– 200 – OK – Everything is Fine– 400 – BAD REQUEST – Something wrong with App– 500 – INTERNAL SERVER APP – Something wrong

with Server

• Not more than 8 Codes– 201 , 304, 404, 401, 403

Versioning

• Never Release without Version– /v1/dogs

• Simple Ordinal Number

• Atleast one version back

• How long to maintain version ?– One Developer Cycle

Pagination & Partial Response

• Pagination– Offset– Limit

• Include Meta Data

• Set Defaults

• Partial Response– As optional Parameter– /dogs?fields=name,color,location

Support Multiple Formats

• Support Multiple Formats of Data– JSON– XML

• Default format ?

• Syntax– Google : ?alt=json– FourSquare : /venue.json– Digg : Accept : application/json

Secure Your APIs

• Many Schools of Thought– OAuth 1.0 a : Twitter– Permissions Service API : Paypal– OAuth 2.0 : Facebook

• What should you do ?– OAuth 2.0

Other API Tips…

• Attribute Names – Camel Case

• Search– /dog?q=red– /owners/5678/dogs?q=fluffy+fur– /search.xml?q=fluffy+fur

• Consolidate API Requests in one domain– Developers.example.com

• Complement with SDKs

Securing your APIs – OAuth 2.0

OAuth 2.0

DeveloperOAuth

OAuth

Access Tokens

Identification info from the requesting application (client ID and secret)

+Resource owner credentials (if needed)

+Optional information about what the application wants to do with the resource (scope)

=Access Token and (optional) refresh token

Access Tokens are credentials that allow access to a protected resource for a specific application to perform only certain actions for a limited period of time.

Refresh Tokens

Identification info from the requesting application (client ID and secret)

+Refresh token

+Optional information about what the application wants to do with the resource (scope)

=Access Token

Refresh Tokens, if provided, represent a limited right to reauthorize the granted access by obtaining new access tokens.

© 2013 Apigee Confidential – All Rights Reserved

Common API Provider Concerns

ProtocolTransformation

Mobile Optimization

Versioning & Enrichment

Security Mediation

Traffic Management

© 2013 Apigee Confidential – All Rights Reserved

Common API Provider Concerns

ProtocolTransformation

Translate between REST to SOAP

Translate between XML & JSON

Mix HTTP and HTTPS Targets

2 Way SSL Target Security

Manage External Data Sources

© 2013 Apigee Confidential – All Rights Reserved

Common API Provider Concerns

Mobile Optimization

Compression & Decompression (gzip)

Manage Pagination

Streaming Payload Options

© 2013 Apigee Confidential – All Rights Reserved

Common API Provider Concerns

Versioning & Enrichment

Emulate Prior Release

Mock New, Unavailable Services

Mashup Data from Different Sources

Mashup Functionality from Different Sources

© 2013 Apigee Confidential – All Rights Reserved

Common API Provider Concerns

Security Mediation

App Level Authentication

User Level Authentication

Custom Attributes/Key Translation

Granular Analytics

© 2013 Apigee Confidential – All Rights Reserved

Common API Provider Concerns

Rate Limit / Quota Management

Spike Arrest

Code Injection Blocking

DoS Protection

Bogus Traffic/Probing Block

Custom Rule Enforcement

Traffic Management

Q & A

https://community.apigee.com

Thank you