So you think JSON is a good idea?

@herval

JSON is cute

● Human readable!● It's what my Javascript uses on the browser!● Everyone uses it on their public APIs!

It's so easy to use! I can just put whatever I want in the response and tell people what to expect!

Cute doesn't pay the bills

JSON is schema-less*● There's no guarantee on what gets returned● Clients may break if you simply add a new

field● CPU and memory intensive

* JSON Schema is a thing, but SRSLY?

JSON parsing is slow

https://github.com/eishay/jvm-serializers/wiki

Cute doesn't pay the bills

Double trouble: JSON over HTTP

● HTTP handshake process is long● You have to reconnect. Every. Single. Call.● Back pressure? ● Circuit breaking?● Everyone documents their APIs differently● Don't even get me started on versioning

Case in point: SoundCloud's Stream

Restful "Microservices" (V1)

Public API

Timeline Service

Graph Service

Content Auth

Storage

Restful "Microservices" (V1)

One API call → ~10-20 internal HTTP calls● Pagination issues (URL length limits)● Versioning not baked in

JSON parsing → 60% of the processing time

Restful "Microservices" - Documentation

A huge README explaining what every single endpoint does.

## Rest API

### Returning the stream for a given userParams:

- cursor (optional) - a string with the id of the previous trackHeaders:

- user-id - the id of the user that owns the stream

```bash$ curl http://timeline.srv/stream -H "user-id: 1"{"events":[{"type":"repost","id":"f0876fe0296cf49985fcd555bd0bcec295cce36c","timestamp":"2014/05/18 18:27:37 +0000","urn":"soundcloud:tracks:732085","actor":"soundcloud:users:5725061","target":"soundcloud:users:80611"}]}%$```

Actual Microservices (V2)

Public API

Timeline Service

Graph Service

Content Auth

Storage

● Replaced heavily used service w/ a Thrift API *

● 100ms less latency per request● Serving the same traffic with ½ the hardware

Actual Microservices (V2)

* http://twitter.github.io/finagle/guide/Protocols.html

Actual Microservices - Documentation

An IDL defining the interface

No misunderstandingsNo unknown paramsNo unexpected responsesNo handwritten parsers

struct TimelineResponse { 1: required list<Event> events 2: optional Cursor nextCursor}

service Timeline { TimelineResponse stream(1: UserSession user, 2: optional Cursor cursor)

TimelineResponse profile(1: UserSession session, 2: Urn user, 3: optional Cursor cursor)}

Do it right once and avoid doing it twice

Migrating away from Rest/JSON is painful● Formalizing an API already in use is hard● Surprise corner cases & parameters● (Usually) too much time spent on

documentation, parsers, code generators, etc → resistance to change

TLDR

● Treat your microservices like little binary components

● Thrift/Protobuf/Avro all excellent● Actual interfaces are a beautiful thing* **

* No, a Readme is not an interface.** No, a Map of Maps of strings is not a good interface.

Thanks!

@herval(let's talk on Twitter!)