Open API design

OPEN API Design Consideration Point

1. API Type 

Internal APIs

Internal System in same network

User for internal user or authorized user

 

External APIs

for Public Developer

Developer Support is key point

 

for Partner

- Business value is key

 

2. API Design Best Practice

Easy to use

with out documentation, API should be easy enough to use.

Easy to Try and use

For private APIs, it is important to demonstrate real value in running a system or app off of the API

public APIs, one approach is to offer some level of free access. Many developers won’t even consider using your API if there are only paid options. At this point in the customer acquisition cycle, the developer may not know if your API meets their needs or if their app’s business model will support paid access.

 

Diffentiate API

Ÿ   The data is unique, more complete, or more accurate than that of your competitors

Ÿ   You offer better support or an easier signup process

Ÿ   Your API is more robust, reliable, cooler, or faster than alternatives

Ÿ   Your terms are more developer friendly; perhaps you offer more data traffic for free or at better rates

Provide mandatory functionality first time and enhance later

There are other aspects of simplicity that can help make your API easier to adopt. One success factor is to stick to conventions that the developer might already know

Target Specific Developer Segment 

3. Technology Selection

REST API

pragmatic REST API design

Figure 1 Wrong design for shopping cart

 

Figure 2 Good design for shopping cart

Binary protocol

Ÿ   Protocol Buffer

Ÿ   Thrift

 

Versioning

Having mediation layer like ESB

4. Security

Identification

- grant access by using API Key

Authenticate

- Determine who is accessing API.

Ÿ   User name & password

Ÿ   Session based

After log in with user name & password, session token key will be issued. with the session key authentication can be passed

Ÿ   Standard way

SAML

OAuth

 

Authentication vs Identification

Identification based API provides same functionalities and data to client.

Authentication based API provides user dependent data to client

Encryption

use SSL (can be attacked by Man in middle attack)

partial or all message encryption

 

Threat Detection and prevention

 

General recommendation of Security

API Keys for only nonsensitive & read-only data.

Use OAuth 2.0 for more sensitive authentication

use SSL for everthin sensitive data.

Sanitize incoming and outgoing data - prevent javascript attack and SQL attack. (especially in writable API)

 

5. Legal Consideration

 

Consideration point

- What content will be provided

- What right can u or do u want to grant the consumer of API

- Are they have different level of API access?

 

Perspective

Ÿ   Contract & Terms of Use

Ÿ   Privacy Policy

Ÿ   Data retention policy

 

6. API Operation

Monitoring

Throttling (Traffic management)

Depends on contract & consumer, API traffic can be managed. It is important to monetization

Reporting

SLA

Issue management

Internal operation issue tracking

Support

Ÿ   Issue management & ticketing

Ÿ   Documentation

Ÿ   Sand box

 

7. API Measurement

Effectiveness measurement - call per day

Effective measurement - call per day, call per client (by region ,model etc)

Performance measurement - response time

 

 

 참고

http://www.layer7tech.com/

http://www.apigee.com