And if everybody does their job correctly, you will see that:

resources, represenations, states, ands state transfers, URI schemas, verbs, content types, serialization, hyper media and linked-data.

are really simple concepts, most of which you already know.

And developers are a crucial constituency

Even the simplest API wants a lib

Remember, people shop compartively for APIs.

And DevEx is important because having your APIs integrated into third party libraries and software is probably the most important avenue for adoption.

Give us some love

I really hope that after these two days, you will have accepted that giving developers some love, is the smart thing to do.

Who giveth love, love receiveth.

This is the present, this is the future; Listen to the smart people that will talk here.

3:30:3 My personal Litmus test

On the homepage of your API

A developer should

1. Understand in 3 seconds what your API is for.
2. Be able to indentify the entry point in 30 seconds.
3. Be able to create an account, call the system, and use the result in under 3 minutes.

3:30:3 If your API passes this test

Boy, are you going to get some love

This is your bright future

But this talk is not about happy and cool.

Legacy cursed be thy name!

What is legacy (software)?

• Well, it is basically every single computer system you have.
• But it is also every single system you are currently building
• and any system you will be building at an point in the future.

You know, the future has this horrible, inexorable tendancy of becoming the past.

The wonderful beautiful world of legacy presentations

• Some ten years ago, some smart geezer, held the same discourse, and told you about the wondreful world of SOAP.
• How it will all automagically work together. UDDI anyone?
• How this was the future.
• Well seeing it is our past, he wasn't all wrong, right?

Assumptions, Assumptions

Hey, you got fooled once, so let's assume, that you will get convinced by all the smart people, again.

(BTW you should be, the smart people are smart…)

Let's also assume you either have internal or public APIs in production

(well, if you have a server somewhere, you forcefully have something)

Now, everybody here is telling you, your systems look like this

You ain't gonna get no love looking like this

…they say

Fashion

Even if you believe this is only a fashion, the latest craze. You should still probably go for it.

Fashion is important; Beauty is imporant. Getting love is important.

But I am beautiful on the inside!

• Of course, your soul is an important thing too.
• You do need to have some intrinsic value.
• But as the others will tell you, there is probably a lot of that value that is currently underutilized because it is locked in, behind layers of opaque complexity.

So how will I get love?

• Let's take our existing systems and modify them to suit the new standard, the old one really seems to have fallen from grace

Let's put on some makeup on the ugly hog

• We will take our XML and transform it to JSON, so the cool new kids stop laughing at us
• We will find every occurence of data getting changed through a GET and modify it to POST

Success?

• Weirdly enough, we are getting more support calls now
• With the old SOAP thing, the clients had a billion integrated tools
• Now we are getting so many questions…

More makeup?

• We will never, ever say "200 Error"
• We will remove the verbs in our urls
• We will put copy-pastable curl in our documentation (extra credit, right?!)

Success?

• Chances are, if you have read the blogs, and followed a bunch of the "best practices" your hog is starting to look like something really different

Still no love

You just may have identified the wrong side of the pig as the source of the problem

We told you, developers also care about smell…

The whole method is wrong

Chances are that if you only try to cosmetically look like a "modern RESTful API"

You are almost getting the 3 Seconds, 30 Seconds, and 3 Minutes thing

But you are failing on the last bit "and use the result".

Seduction is as much about hiding

Chances are you are exposing internals that have nothing to do with what the person on the other side of the line is trying to achieve.

• They will see it in the ugly URLS
• They will see it in the weird field names
• They will see it in weird values appearing in fields
• They will see it in fields that are "required" but it is really hard to know why

APIs need design

• If all you do is emulate the aesthetics, you will not leverage the new efficiencies proposed by the ReST model
• If all you do is emulate the aesthetics, you won't be fooling nobody
• Your API is not a by-product of what your systems currently do
• It is by and in itself a product
• And products need design

Design starts through considering experience and usability

You must not start with "What your system does" and how to "Expose your functionalities", but with the usecase and workflow of the developer that is going to use it.

Design starts through considering experience and usability

• Complexity is not evil; Life is complex
• But a complex reality needs to be discovered step by step
• Your API not only needs to efficiently allow people to interact with your systems
• It must, by its own structure allow them to discover it, step by step

All APIs share at least one usecase

a developer will have used them for the first time, without knowing precisely how they work

So how do go about it?

• As always start from the furthest part of your system and work in
• Start from the first seconds someone discovers your system and follow his experience

Identify value first, features later

• Identify your unique value proposition, what information do you have that people really, really want?
• What are the things they are currently doing by hand, extremly often, that can be automated?

• What would they pay for?

• (and maybe what are the things you have to do manually, but want the client to do for you…)

Critical Path to Developer Experience

Now you MUST remain oblivious to how your systems currently work.

What databases you use, how they are structured. What your runtime or framework is. If you have firewalls; If legal says its ok. If you must follow PCI-DSS. Focus on the user.

Laser beam focus

• Chose from those elements of information or automation candidates, just a single thing.
• Identify what is the absolute minimal information you need from the second party in order to fulfill it
• Identify what is the absolute minimal path that is needed to get that information from the user to you

Constraints emerge, patterns follow

• Here you might discover your need for authentication
• Here you might discover your need for a collection/item pattern
• Identify what is the minimal subset of information you can send the other party that delivers this value.

You focused on the user. This has been a good day. Relax. Drink a margarita. Tomorrow is going to be harder

Time for introspection

• You know, because of the fashion thing that when your API materalizes it will need to follow all of the nice guidelines you will learn about
• It is probably going to be ReSTful, implement hypermedia and respect content types
• Good time to start reading about ReST API implementation. But don't write code. Maybe just draw a state diagram on a piece of paper
• We do start to have a URI plan
• You are not interested yet in how you represent the resource

In ReSTSpeak you probably identified a resource and a method or two

You now need to start the hard work of bridging this to whatever internal artifacts you have

Build a bridge, a proxy, a facade

• You now know the maximal amount of information you are going to ask for, and the maximal amount of information you are going to give
• If your internal systems having a billion "optionally required" options, you know this is when you start setting "reasonable defaults"
• Calling three seperate internal system and exposing a single response

Don't bind directly

• As I told you, even the current system you are working on is going to be "legacy" soon
• You want to be able to version the API independently from your other systems
• And there is a very good chance you might have to maintain simultaneously multiple versions of your API

Not binding directly is a good thing

• It will allow you to use an intermediate system for your API that does that really well
• Like the cool kids do
• You will be able to do the same with your J2EE system, you will be able to do this in PHP
• It is just going to be so much harder, and you will run into so many performance issues.

Don't bind directly

• Chances are you have a bunch of CamelCased, Originally 8 Uppercase fieldnames. No one wants to see those.
• (and if you are French, they are most probably in Franglais)
• Respect the work you have done so far. You know what are the fieldnames, if your internal ones don't match (they won't). Translate them.

Implement

• We only have one or two resources to bridge
• We are allowed to use cool toys
• Look at what the other cool guys are doing, emulate, but don't copy
• Strive for a coherent, simple, minimal style
• So this is going to be very, very easy to do

Learn

• Time to eat your dog food
• Use the API yourself, internally, play with it
• Have internal people that did not participate in its design play with it
• Ask them where they have blocked, document this
• Of course, it only does one small thing, but hey, you have identified some real value right?

Learn more

• If internally no one wants to play, have you identified any real value?
• If you now discover that you need multiple calls to the API to do anything useful, we have a problem
• Go read you some articles about the best practices now
  • How you always paginate lists
  • How sometimes you embed another resource

I corrected those, production now?

• OH no! Documentation and client libraries, and maybe a nice console
• Document externally with the simplest form possible. With those copy-pastable examples. Put examples of output.
• Document internally the best practices you decided to follow. Your design principles. Do it RFC style "MUST", "SHOULD". SemVer this document with the same version your API has.
• If you did your job correctly on the first stage, this is easy peasy.

I did that, production now?

• Well, if documenting and writing libraries was hard, stop;
• You either have a design issue or an implementation issue. You passed so little time on this until now it is really cheap to start over

And now, production?

• Probably not; Maybe not.. you might need some orchestration, monitoring, rate limiting and such.
• Also, sadly, you might not yet have a minimal marketable feature set with a single resource.
• Time to iterate. Add a another one.
• Are you able to change nothing from the initial design?
• Are there new constraints emerging? New patterns?
• If there are new patterns, go back to the first resource implementation and check it is coherent.
• Do we need to change the design of the bridge?

ReST is not only an "Architecture Style"

• Don't think of you API as a big strategic project
• Think in terms of a product design process that will continue on. You will have to add stuff to the bridge, you will want to add features to the API, you will want to keep this coherent
• This is not a standard, don't blindly use automagic tools. Fashion will change. (But only stray from emergent standards when there is a good reason to)
• You have decoupled the implemenation of the API. So you know V2 will be able to follow the new cool.

Production!

About me

Ori Pekelman

@OriPekelman

http://www.constellationmatrix.com

http://dev.af83.com