A 5 minutes rundown on some of the most glaring downsides of microservices/SOA using JSON endpoints instead of proper interfaces.

1. So you think JSON is a
good idea?
@herval

2. 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!

3. 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?

4. JSON parsing is slow
https://github.com/eishay/jvm-serializers/wiki
Cute doesn't pay the bills

5. 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

6. Case in point: SoundCloud's Stream

7. Restful "Microservices" (V1)
Public
API
Timeline
Service
Graph
Service
Content
Auth
Storage

8. 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

9. Restful "Microservices" - Documentation
A huge README explaining what every single
endpoint does.
## Rest API
### Returning the stream for a given user
Params:
- cursor (optional) - a string with the id of the previous track
Headers:
- 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"}]}%$
```

10. Actual Microservices (V2)
Public
API
Timeline
Service
Graph
Service
Content
Auth
Storage

11. ● 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

12. Actual Microservices - Documentation
An IDL defining the interface
No misunderstandings
No unknown params
No unexpected responses
No 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)
}

13. 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

14. 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.

15. Thanks!
@herval
(let's talk on Twitter!)