“Experience API” defines Every API

Daniel Jacobson, Director of Engineering – Netflix API, uses some terms in his post, The future of API design: The orchestration layer, that are making things difficult for those of us trying to communicate in the API space. Specifically, the two terms, “API Orchestration Layer” and “Experience API.” These are neither accurate nor meaningful. Let me explain…

API Orchestration Layer

From Daniel’s post:

An API Orchestration Layer (OL) is an abstraction layer that takes generically-modeled data elements and/or features and prepares them in a more specific way for a targeted developer or application

This concept is describing an Aggregation Layer, not an orchestration layer. Per the almighty, always-true, Wikipedia:

Orchestration describes the automated arrangement, coordination, and management of complex computer systems, middleware, and services.

An orchestration layer determines order and sequence, orchestrating events and sequencing of messages in a service-oriented architecture. On the other hand, an aggregation layer performs operations and data transformation to provide a specific payload for a specific client. Both are useful, but don’t confuse the two.

Let’s talk about aggregation where we mean aggregation and orchestration where we mean orchestration.

Experience APIs

There is no such distinction. Nor should there be. Let me be clear: Every API is an experience API!

Make no mistake, no matter whether you’re targeting internal develops, third-party integrators or public developers, those folks have an experience with your API (good or otherwise). However, now I’m hearing businesses talking about how they don’t need to design their RESTful APIs, since they’re just going to put an “experience API” on top of it. Please stop using the term.

Appropriate alternatives are: Public API, Internal API, Crappy API, REST API, etc.

In Short

APIs are the new and shiny thing that businesses are currently chasing for the sake of being part of the so-called “API economy.” Understanding is important. APIs are confusing enough without using a ubiquitous language to describe what we mean. Can we agree to use accurate terms?

RestExpress API Application Layers

Here’s a quickie video describing the application layers of a RestExpress application when one of the Maven Archetypes is used to create a new RestExpress project.

http://youtu.be/ZFqjvNiB-hY

To summarize: Visibility or “awareness” goes down. Meaning that a layer can call (or know about) the layer immediately below it, but an application layer cannot call the layer above it or a layer deeper than the next immediately lower. In other words, if there’s database orchestration code in the Service Layer or Controller, that’s poor design. And conversely, if there’s HTTP header, request or response manipulation in the ServiceLayer or Persistence Layer, that’d be bad.

Layer #1: Controller/HTTP Layer

HTTP layer where requests, headers and responses are manipulated and processed.
Handles serialization of request body to domain model.
And deserialization from domain model to response.
Makes call to only the Service Layer (layer #2).

Layer #2: Service Layer

Business logic.
Calls methods on domain model to orchestrate business logic and domain functionality.
Calls Persistence Layer to store and read domain model instances.
Returns domain model instances to the Controller/ HTTP Layer.

Layer #3: Persistence Layer

Sometimes call DAL (data access layer) or DAO (data accessor object).
Called Repository by Eric Evans in his Domain Driven Design (DDD) book.
Creates an interface to perform queries and database operations.
“Serializes” and “deserializes” domain model instances to/from the database.

The Commoditization of the User Interface

The public face of a business system is its user interface (UI)–the part the end-user sees. Businesses often think in terms of user interface design. Many times they also consider it the facet that gives them an edge in their market (the “killer app”). Being overly concerned with the UI first, focusing on what the web interface or mobile application looks like, often means duplicating complicated business logic across those UIs. This makes the user interface very difficult to maintain and morph over time as business needs shift.

The Problem

Mobile-first is a term that’s created a lot of buzz lately. So much so as to render the term largely meaningless. However, it does point to a great need: the need to revise or even provide new user interfaces for business systems as channels change and new ones become available. But with all that complicated business logic captured in Web applications, JavaScript, native IOS and Android applications, it’s very expensive to start over when creating a new user interface.

We need to be able to throw UIs away and start over with minimal cost. Or create new UIs for new channels and/or devices without duplicating all that business logic. The real asset must be the business logic encapsulated in our back-end business systems. These systems should provide the ability to be UI agnostic. In other words, the face of the business system (e.g. user interface) should be able to change drastically over time without compromising business processes and should have minimal cost.

This is not the case today.

Enter the Shiny REST

APIs should encapsulate both processes and data

There’s a shiny new kid on the block called REST APIs. Maybe you’ve heard of them? They promise easy integration, new business partners, reduced time to market, reduced development cost, increased revenue models, more income, improved creativity & innovation, architectural coolness, singing angels, and maybe even the voice of God saying, “Well done!” At least if you listen to the hype.

In most Web applications, such as Java/JSP stacks, the user interface is intrinsically linked to the back-end business logic and right down to the database. And while service-oriented architectures (SOA) encourages loose coupling between components, the focus is on behavior not data. Putting a UI on those processes is difficult.

The promise of REST APIs is largely that business logic and data is encapsulated behind a suite of HTTP resources. However, at the time of this writing, most businesses seem to be looking at REST APIs because they’re new and shiny, much like businesses “needed” a website to be successful in the late nineties.

The promise has yet to be realized!

Business systems are both data and process. The problem with most Web APIs (we can argue whether they’re truly REST-ful later) is that they only expose data to the outside world, excluding business processes altogether. Typically, the sequence of API calls and details about state changes are shared out-of-band in documentation about the API and are not part of the API request/response cycle itself. This inhibits business logic from being part of the API and pushes business logic into any user interface written on that API.

This is not optimal, in case you were wondering.

To realize the dream, an API must encapsulate both processes and data!

An API for Processes?

Modeling processing within a REST/Web API may seem foreign at first. At least until we consider that HTML has supported the concept for years, with links, inputs, and forms. Leveraging these concepts within a REST API (right in a JSON payload), we can take our APIs to the next level, encapsulating both data and business logic.

In essence, by using links and forms in our REST APIs, our APIs become more like state machines. These state machines, with both data and behavior (transitions), can model extremely scalable, maintainable, arbitrarily-complex business processes.

This is the realization of Roy Fielding’s “hypertext as the engine of application state” (HATEOAS) constraint of REST.

So how do we model a data and behavior in an API? In essence, it’s media types that enable us to expose links, actions and forms within our API payloads. Which, in turn, enable us to model complex business processes without moving that business logic to the client.

State-Machine APIs

As mentioned, a typical API response today will only contain data. More advanced ones expose links (say via the HAL media type). Even more advanced representations, capable of modeling state machines, contain more-than just links and data, adding actions and forms. Media types such as the Siren, Collection+JSON, and HALe are good examples.

Consider the following simple state-machine diagram.

In it are two states, state A & state B. The state-machine changes from state A to state B when event C occurs (note that the state-machine must be in state A for event C to occur). Additionally, the state machine goes from state B to state A when event D occurs.

A Lighting System Example

If the above state machine is implemented by a REST API with states A & B represented by JSON and the events are generated by actions on that API. Let’s say the API represents a lighting system with off & on states (representing state A and B, respectively), with events of turn-on and turn-off (representing events C and D, respectively).

Initial state A of off might be represented in JSON (using my own invented state-machine media type) as:

{
    "status":"off",
    "_actions":{
        "turn-on":{
            "href":"http://api.example.com/lights",
            "method":"POST",
            "data":{
                "status":"ON"
            }
        }
    }
}

From this representation, we know that the status of the light is off and that we have the capability to execute the turn-on action by calling:

POST /lights
HOST: http://api.example.com
{
    "status":"ON"
}

Whereupon the API makes the state transition and responds to the turn-on action with something like the following:

{
    "status":"on",
    "_actions":{
        "turn-off":{
            "href":"http://api.example.com/lights",
            "method":"POST",
            "data":{
                "status":"OFF"
            }
        }
    }
}

Conclusion

Although the above example is extremely simple, it illustrates the key point that a user interface for our lighting system could be created without any business logic since the API contains all the possible actions that the user interface can make.

There’s no URL construction within the UI code base, no if-then-else logic to determine possible actions based on the value of the status property. It only needs to utilize the possible actions in the _actions property.

This is very powerful. APIs of the future will enable the commoditization of the user interface by encapsulating both data and business logic.

What are your thoughts? Enter a comment below about your thoughts and experiences.

Building a 1×12 Guitar Speaker Cabinet

1x12 Speaker Cabinet As an amateur electric guitarist, one eventually begins to seek a better sound. Tube amps are supposed to be the bomb, right? Well, some time ago, I bought a Blackheart Little Giant 5 amp, used. It’s a single-channel 5W, single-ended, class A amp powered by an EL84 and voiced through a 12AX7 preamp tube. Not a bad sounding amp at low volumes, with some crunch at high volumes. Not a lot of clean headroom, but not bad either substituting a JJ 12AU7 in place of the original 12AX7, which to my ear gave it lower gain (volume), but not much and warmed up the tone significantly, with boosted low end. I also replaced the original EL84 and replaced it with a JJ EL84, which made the tone less harsh to my ear. Your mileage, of course, may vary.

I had the amp plugged into an open-back cabinet with a cheaper Celestion 12-inch speaker. Sound == crummy, where crummy is harsh, jarring, ice-picky and overall ragged, with almost no bottom end. The speaker almost sounded blown. I thought I’d fix it by buying a new speaker and ended up with an Eminence “The Governor,” which is supposed to work for both open- and closed-back scenarios.

“The Governor” has a lot of mids (some say it’s a good match for a Celestion Veteran 30) with a tight bottom end. After mounting it and hooking it up, the speaker still sounded ragged, almost blown at times–I call it “flubby”–in that open backed cabinet. It just sounded like a big fart factory, IMHO (“Hated it…”) It was not in any way endearing, so I began to shop for a cabinet, but didn’t really want to spend $300-500 on a nice cabinet after already spending ~$100 on a new speaker.

Purpose

For my purposes, if I play publicly, it’s in venues where mic’ing is the primary form of amplification. But my primary purpose for this rig is recording. Hence the small-wattage amp and single speaker combo. For these purposes, I like the design of the Mesa Boogie Wide Body Closed-Back cabinet, but was afraid that my “The Governor” speaker wouldn’t sound as good if I replicated the cabinet size exactly, if I was going to build my own.

Enter Speaker Design

Leveraging some of my old hi-fi speaker design books (I built a set of stereo speakers in high school) and the Google, I created a spreadsheet of calculations based on the Small & Thiele parameters of the Eminence speaker (you can download it here). Sure enough, based on my calculations “The Governor” is best in a ported speaker cabinet, with an EBP of 171 (see column D8 of the spreadsheet). You can input your own speaker parameters into it and have things recalculate for you, but the spreadsheet wasn’t really designed to be clear, concise and consumer friendly. It worked for me, but use at your own risk!

As I intended to use standard lumber of 1″ x 12″ for the outside of the box, this dictated the depth of the cabinet to approximately 11 1/2″ deep (note my inexperience with standard lumber sizes as it turns out a 1×12 is more like 3/4″ x 11 3/8, not width of 11-1/2. Close ’nuff being only an eighth of an inch off). After mucking about with frequencies, tunings and box sizes I narrowed in on a size of 11 1/2″ deep x 22 1/2″ wide x 16 1/2″ high (outside dimensions). With a port size of 3 1/4″ x 7 5/16″ (approximate area of 23.7583″) and the inside the box volume of 1.83 cubic feet, I’d have a cabinet tuned for my “The Governor” speaker with a cutoff frequency below 82.41 herz, which is the frequency of the low-E string. Amazingly enough, it came out really close (though not exact) to the size of the Mesa cabinet measurements listed on Mesa-Boogie site… that gave me some confidence to start cutting.

The Materials

Most cabinets these days are made of void-free birch plywood. However, that’s $50 or so per 4×8 sheet, and I didn’t need that much wood. Plus, the old classic cabinets, like the Fender and Marshall, were originally constructed of solid pine, reportedly. Pine is cheap. Pine is supposed to also add a nice, round, warm tone. And since I’m not a traveling musician, I decided to go the cheap, er… “classic” route, using plywood only for the front baffle and back of the cabinet.

Here’s a list of the wood that I used as a shopping list (at Home Depot):

1 – 1x12x8 common pine board (outside of cabinet).
1 – 1x3x6 common pine board (to rip for furring strips inside cabinet). Should have used plywood or hardwood instead.
1 – 24×48 birch plywood scrap, sanded (front and back baffles).

Other than that I used:

wood glue
1-1/4″ drywall screws
flat black spray paint
spray adhesive (for holding the grill cloth in place)
staples (to back-up the glue on the grill cloth)
polyurethane
1 tube clear caulking
a bunch of c-nuts (due to my mistake of pre-drilling the back furring strips)
cabinet hardware: handle, rubber feet, finish screws and washers, speaker cloth.

Tools used (Tim “the tool man” Taylor would be proud):

Drill and bits
Table saw
Circular saw (for ripping the plywood)
Router
Staple gun (for grill cloth)
Belt sander (to even out the box joints)
Finishing sander (used 400 grit to smooth out the wood and finish between coats)
Makita screw driver (and hand one also)
Countersink bit
Miter saw (for cutting the firring strips accurately)
Sabre saw (for cutting out speaker hole and port)
Wood rasp (for evening out the sabre saw cuts)
Sanding block
Hammer (for seating the c-nuts)
Wood plane (for reducing the width of the front baffle ever-so-slightly to account for the grill cloth)

Putting it Together

Ok. So enough talk already! Let’s get to the implementation…

The first step is to create the outside of the cabinet. Rip the 1×4 into strips and screw-and-glue them in the corners.

Then glue the corners together to create the box.

speaker-cab3

Glue-n-screw furring strips around the rest of inside of the cabinet. Note how I pre-drilled holes in the furring strips. This was a good idea for the FRONT of the cabinet, but not the back. The front, I wanted to screw from the inside, but the back then cannot be. It has to be screwed from the outside. Oops! So now I have to add nuts to the inside furring strip to hold the back on. Do not do this when you build yours…

The picture below shows the cabinet box after belt sanding the sides and routing the corners to round them over. I used a 1/4″ round-over router bit. Next time I’d try a 1/2″ round-over bit since standard metal cabinet corners match that radius. Using the size I did means that I cannot really put metal corner protectors on this cabinet–and it’s soft pine. Longevity could be an issue if this cabinet gets transported much.

speaker-cab4

Trial-fitting the front baffle board with speaker and port holes cut and rounded. Looking good so far… This baffle board will be spray painted flat black on the front to make sure the light wood doesn’t show through the speaker grill cloth.

Time to paint the baffle board and finish the cabinet. I used brush-on Varathane, but was very disappointed with my brushing abilities and brushes. I ended up with bristles in my finish and brush marks galore. It’s the brush’s fault, honest! I spent quite a bit of time sanding a fair amount of finish off and going to a spray can. That worked much better, but I still am not completely happy with my technique. There’s a run and some dry patches but the wood is protected. I would have liked a bit darker finish too. Next time I may use some stain instead of a clear only finish. However, pine darkens with age anyway, and after all it’s about the tone, man!

speaker-cab5

Here is the baffle board, painted with grill cloth in place on the finished cabinet. The grill cloth is simply held in place on the baffle board by spraying adhesive on the back edges, wrapping the cloth around then stapling it. After that, I caulked the baffle board seating surface heavily and screwed the baffle board in place through the pre-drilled holes. It’s not coming off easily–or vibrating. Plus, it’s well sealed.

20130831_132336

Here’s the front view at this point.

20130831_132358

Time to mount “The Governor” in place. There are c-nuts embedded in the front of the baffle board enabling the screws to go through from the speaker side. I glued the c-nuts in place so I didn’t accidentally push them back out again while mounting the speaker. Conceivably, I could’ve just used wood screws to hold the speaker on, but I was afraid they’d eventually strip out of the plywood baffle and wanted it more robust.

There are also c-nuts in the back of the furring strips that will hold the cabinet back in place.

20130831_141251

I routed the back for the jack plate and used a hole saw to cut out the remaining material for the jack and wiring to go through. Sloppy routing but effective.

20130831_145159

I filled in the edges with caulking and placed the jack plate. No air leakage from behind there! It also won’t come off or resonate that way.

20130831_150135

Again, here’s the front view:

1x12 Speaker Cabinet

And the back view, with a naked Blackheart Bh5h sitting on top (more on that later):

20130831_160722

The Results

So how does it sound, you ask? Well, the sealed, ported cabinet took all the “flubbiness” out of the speaker and cleaned up the sound quite a lot, staying smoother through much more volume range. It also boosted the bottom end so it’s nice and well-rounded. Now I can hear that I have to do some more work on the amp to tweak the EQ a bit. But overall, I’m extremely happy with the improvement in tone. Additionally, it’s REALLY loud! I don’t have to turn the amp up as high (maybe 2-4) to have the room rockin’ which gives me enough clean headroom at that volume to do some recording. Stay tuned for another post with sound samples.

Now let’s get down to some playin’!

RestExpress Still Top Performing MongoDB REST Framework

Benchmark results Round six of the TechEmpower.com Web Framework benchmarks were published on July 2, 2013, which show RestExpress 0.9.2 as still the best performing REST Framework against MongoDB (2.2.4) for single-query, CRUD-style operations. At 63,209 responses per second on an i7-2600K (with 8GB memory) and 7,547 responses per second on an AWS EC2 m1.large instance, it ranked 10th and 11th respectively, overall. But was the highest-ranked framework using MongoDB as it’s back-end store.

Another test, which makes 20 queries per request, showed RestExpress to also rank well for MongoDB-backed services, ranking top the list for EC2 and second only to NodeJS on the i7.

As RestExpress 0.9.2 is using Netty 3.6.x, it’s conceivable that there will be significant performance increases realized when the upgrade to Netty 4.0.x is completed. But the performance numbers are still very encouraging.

Read the full report here… http://www.techempower.com/benchmarks/