Service-Oriented Architecture:

Benefits
Isolation:
language, technology, tools
decoupling, independency
deployment and maintenance
Ownership: minimal gray area and gap
Scalability: easy to scale up and modify
Cons
Complexity: sometimes unnecessary
Latency: Network communication eats time
Test effort: all services require E2E tests
DevOp, On-call

APIs

An Application Programming Interface(API) is best though of as a contract provided by one piece of computer software to another.

Classification of APIs

Web Service APIs: SOAP, XML-RPC, JSON-RPC, REST
Library-based APIs: JavaScript(Google Map APIs)
Class-based APIs: Java API, Android API
OS functions and Routines: File system, user interface
Hardware APIs: Cameras

RPC v.s. REST

RPC
Remote Procedure Call is a protocol that one program can use to request a service from a program located in another computer on a network on a network without having to understand the network’s details

RPC call is more like a local function call
E.g.

1	http://<host>:<port>/service?request=GetOrders?orderId=123

Representational State Transfer(RESTful)
is an architecture style for designing networked applications. The idea is that, rather than using complex mechanisms such as CORBA, RPC or SOAP to connect between machines, simple HTTP is used to make calls between machines.

REST is like a HTTP request.

E.g.

1	http://<host>:<port>/service/orders?orderId=123

Comparison

RPC
Pros:
Action Oriented;
RPC is transparent: it is like a local procedure call;
RPC is strictly defined: client must know method name, arguments and types to make a call;
RPC is heavily used in big tech companies
适合SOA架构，API定义清晰

Cons:
RPC is difficult to modify: both server and client need to change.

REST

Pros:
Resource oriented;
Easy to modify: client doesn’t need to dependent on method name, arguments or types. It depends on message format;
Easy to cache.
适合前端架构

Cons:
Format can be changed;
Hard to do authentication.

JSON RPC vs XML-RPC

JSON: less space; easy to read

Package: pyjsonrpc

API design

why API design important?

APIs can be one of greatest assets of companies
API can also be one of greatest liabilities of companies
Public APIs are forever

Why API design important to YOU?

We are natural API designers;
Useful modules tend to get reused;
Good API means great code quality.

Characteristics of Good APIs

Easy to learn and use with good documentation;
Hard to misuse;
Easy to read and maintain the code that uses it;
Sufficient powerful to satisfy requirements;
Easy to extend.

API design principles

Functionality should be easy to explain;
If it’s hard to name, that’s generally a bad sign;
Good names drive development.