#api-design

So I am trying this new API design concept. I know it has been done before but I do not know if it has an official name.

I need your help!

When you read this and you recognize it and know the name, let me know because I want to learn what it is really called. For now, I am going to call it, Front-End First API Design Pattern, or FEFADP for short... yea, we need a better name.

What do I usually do when I am building an API?

Usually, when I design an API, I am inside the guts of the API, vetting out all the details of what the API parts will be. I define the data each endpoint receives and the data each endpoint returns. I work through a lot of the error handling scenarios, figuring out which HTTP response codes to be used and what type of error messages to return.

After I have all of that figured out, I usually build a part of the app around that endpoint. Sometimes, I leave out the error handling until later but regardless, it is similar to that flow.

What am I trying this time when building an API?

This time, I created a bunch of endpoints I know I will need. These endpoints don't do much, they only return mock data. They also do not do anything to the data passed to each endpoint.

var mock_section = {

  content: '__Some content__',

  markup: '<p><strong>Some content</strong></p>',

  _id: 1

};

...

.get('^/sections$', function(handle) {

  env.response.statusCode = 200;

  env.response.body = [mock_section, mock_section];

  next(env)

})

.get('^/sections/:id$', function(handle) {

  env.response.statusCode = 200;

  env.response.body = mock_section;

  next(env)

})

...

The way I am designing the API is directly from the implementation of the application I am building. I am literally building the client experience where I am implementing services within my app to hit these endpoints and modifying the mock data returned to what I need in the application. I am also adding new endpoints as I hit certain places within the app... ex. After I create a new section, I will need to edit that section. So I create an edit endpoint for that user experience.

How is this helping me?

It is allowing me to rapidly change the API design without a ton of time invested in developing it at first.

It helps me figure out what I need and how I will use it because I do not have everything figured out from the beginning. This has allowed my app development to be more flexible instead of working inside a rigid API which already exists.

Doing it this way also helps me find ways to optimize accessing data within the API so that I do not create odd scenarios where I would need to jump through hoops before hitting a specific endpoint.

What is next?

My goal is to develop the entire app following this design pattern, helping me shape what my API should look and act like. Instead of me guessing which endpoints I will need before building an app, I will know exactly what I need in my API because the app literally defined what is needed. From this, I will build the actual API which receives and returns for-realz data.

Boomski!

I will give an update in a bit about how this is going and I am curious on your thoughts.

Have you tried this before? If so, how did it go?

That is all,

In most functional programming languages, map is a function which takes two arguments, a function and a list, then returns a new list where the function has been applied to each element. That is, map(f, [a, b, c]) returns the list [f(a), f(b), f(c)]. Many operations performed in the course of programming can be expressed in terms of map, providing a common structure for expressing computational tasks.

The functional programming primitive map is a powerful tool both in purely functional languages and in imperative languages like MATLAB. Since relatively recently, MATLAB has included implementations of map built in to the MATLAB standard library. I say "implementations" because MATLAB actually includes three different functions which implement map, but behave slightly differently: arrayfun, cellfun and structfun.

These different implementations each act on a different data type, so that arrayfun acts on each element of an ordinary array, cellfun on each element of a cell array and structfun on the values stored in each field a of structure array. The options and semantics of these three implementations are not identical (for example, cellfun allows one to use a string to name one of several predefined functions, but the documentation of arrayfun and structfun make no reference to the function being specified as a string), forcing the programmer to remember and be aware of these non-uniformities when selecting a data type.

Lately I've been playing with node.js a bit. If you've been living under a rock and don't know it, node is a set of libraries for javascript, implemented on top of Google's wonderful V8. It's pretty neat, and it's package manager utility: npm, is just awesome.

With node you can create a streaming http client just with a few lines of javascript, like this:

https://gist.github.com/1623715

There's a lot of talk going on about node scalability, performance, memory use, etc. This time I want to focus on a different thing: api design.

Let's take the web server example again and see the api that's presented to us:

https://gist.github.com/1623720

The response object we get is just a handle for us to subscribe to (or observe) certain events. While weird at first, this is a really elegant design decision. We don't need to inspect status codes or stuff, we just subscribe to the data event if we want to parse the response, or the error event if we want additional error handling. None of these are mandatory and there are no if/switch statements.

Unfortunately this requires a change in our mindset, it's harder if you're not fond of javascript and specially if you come from a language where functions are not first-class citizens (e.g. java). To make things worse, there are some node libraries out there that do not work this way. Let's go and create our own non-evented api, a simple "Calculator":

https://gist.github.com/1623948

As you can see we now have to check for the value of err (what is err anyway? a flag, an object with error information?) and do some conditional handling. While not very ugly, this whole "2 value callback" is not elegant. What happens if there's another outcome of the method (not just error or data)? In this silly example that's a non-issue, but you sure can tell this doesn't scale. Alternatives are passing in another parameter, which would break backwards compatibility, or adding information to the error object, mixing concerns. This is clearly why node developers use the evented api over this err, data thing for non-trivial callbacks.

Fear not since doing this is not hard at all, in fact its so simple that we're going to do that now in about the same lines of code:

https://gist.github.com/1623971

We're using EventEmitter, a class that's part of node's library (the object you get from an http response inherits from it too). Feel free to dig into the docs, but the most important methods of it are emit, which is used to fire events, and on which attaches handlers to particular events. Those handlers receive the parameters provided to the emit method.

Our example is really simple, almost stupid, you probably won't see the gain here. But suppose you're clients are only interested in knowing if the sum is negative, you could then emit a negative event. Hopefully you'll see how this scales to more complex apis with a few callbacks.