Using the Drupal Services module for REST access to entities, part 1

drupal-logo

I’m not an expert on Drupal, but I do have some extensive experience designing and using APIs.

Recently I’ve been working with Drupal v7, and in particular, getting Drupal to expose a REST interface that would allow me to program against it. I want to write apps that read forum posts, write forum posts, read or post pages, create users, and so on.

Drupal is a server than manages entities, right? This function is primarily exposed via a web UI, btu that UI is just a detail. Drupal should be able to expose an API that is similarly capable. Should be!

The bazaar is alive and well with Drupal. It seems that regardless what you want to do with Drupal, there are 13 different ways to do it. And exposing Drupal entities as resources in a RESTful interface, is no different. There are numerous modules designed to help in this task, some of which are complementary to each other, some of which are overlapping, and most of which are poorly documented. Every module has multiple different versions, and every module works with multiple different versions of drupal. So figuring out the best way to proceed, for a Drupal novice like me, is not easy.

Disclaimer: What follows is what I’ve found. If a Drupal expert reads this and thinks, “Dude, you’re way off!” I am very willing to accept constructive suggestions. I’d like to know the best way to proceed. This is what I tried.

The Services Module

I used the Services module. There are other options – restws is one of them. I didn’t have a firm set of criteria for choosing one versus the other, except that I fell into the put of success more easily with the Services module. IT seems to be more popular and has more examples available that I found via google search.

Services 3.0 is now available. … Note that currently there is no upgrade path for Services 3, and it is not backwards compatible with older implementations of the API. Therefore some existing modules like JSON Server and AMFPHP will not work with it. …

Not that there aren’t problems with it. The lack of backwards compatibility on a programmable interface is a really bad sign (See the blockquote). That reflects poor planning on the designer’s part. And then there is the lack of clear documentation for how to do most things.

Setup

The first thing: you need to obtain and activate the Services module. There’s a straightforward guide for doing this. I installed the module, then went to the Admin panel to insure the Rest Server was enabled. A screenshot is below.

screenshot-20150317-092348

Retrieving Nodes is Easy

Once you have the Rest server enabled, getting an index of the nodes in a drupal system is probably the most basic thing any programmer will want to do. And beyond that, creating a new node (posting a page or article), creating a user, and so on. For the Services module, there is a nice page that gives examples for doing this sort of basic thing. I’m not really a fan of the layout of that page of documentation; it seems to be all over the place, providing basic REST principles, describing REST testing tools, and then finally giving samples of messages. Those things seem like they all belong on separate, hyperlinked pages. But again, it’s the bazaar, and someone contributed that doc all by himself. If I think it could be better I am welcome to edit that page, I guess.

Here’s one example request from that page:

POST http://services.example.com/rest/user/register
Content-Type: application/json
{
“name”:”services_user_1″,
“pass”:”password”,
“mail”:”services_user_1@example.com”
}

This is something I can understand. Many of the other doc pages give jQuery example code. Ummmm…..I don’t write in jQuery. Why not just show the messages that need to be sent to the Drupal server, and let the jQuery people figure out how to type in their ajax methods? ….

The basic examples given here are good but you’ll notice there is nothing there about authentication. Nothing that shows how a developer needs to authenticate to Drupal via the Services module. That ought to be another hyperlinked page, no?

Authentication

There are multiple steps involved to authenticate:

  1. Obtain a CSRF token
  2. Invoke the login API, passing the token
  3. Get a Cookie and new token in response – the cookie is of the form {{Session-Name}}={{Session-id}}. Both the session name and id are returned in the json payload as well, along with a new CSRF token.
  4. Pass the cookie and the new token to all future requests
  5. Logout when finished, via POST /user/logout

More detail on all of this in the next post.



Developer , ,

Adopting Microservices means speed

“it’s crucial to adopt a four-tier application architecture in which applications are developed and deployed as sets of microservices.”

I love this article from the nginx.com website, courtesy of Hacker News. Very good overview of the “microservices” meme that is currently rippling through the industry. This is stuff we’ve all known – heck, we’ve been doing SOA for 10+ years – but the new term is helping to organize thoughts and understanding about why services as a metaphor is important, why services need to be lightweight, why service contracts (APIs!) need to be loose and forward-compatible, why the development of cooperating services must be done independently.

“It’s becoming increasingly clear that if you keep using development processes and application architectures that worked just fine ten years ago, you simply can’t move fast enough to capture and hold the interest of mobile users who can choose from an ever-growing number of apps.”

Oh yeah! Preach it!

The article discusses Netflix and their adoption of the microservices architecture.

I really respect Netflix as a company that moves quickly and constantly adjusts, seeking optimized architectures to address business problems. All the talking and proselytizing they’re doing around microservices is just the latest reason to really like them. I also really hate Netflix as my children seem to be unable to resist the service for even 15 minutes. Me and Netflix – It’s complicated.

Independent of Netflix and the microservices topic, nginx is also really cool. I found it super easy to configure to accomplish some nifty things in some of my work.



Architecture , , ,

Pretty psyched about Swagger Editor for APIs

I’m pretty excited about the Swagger editor. But to understand why, you first need to know what Swagger is all about.

Let’s take a step back. As of August 2014, total activity on smartphones and tablets accounted for ~60% of digital media time spent in the U.S. This unabated growth in mobile is driving the growth in enabling technologies: tools for developing apps, managing app communications, measuring app and data usage, analyzing usage and predicting behavior based on that usage. APIs are a key connective technology, allowing innovative mobile apps use APIs to access data and services from companies like Uber or Twitter, or from government bodies like the State of Washington. APIs provide the linkage.

APIs are not solely about mobile apps. They can be used to connect “any app” to “any service”; indeed this website uses code running on the server to invoke the Twitter API to display tweets on the right hand side of this blog. But mobile is the driver. Web is not driving the growth, nor is the Internet-of-Things; not in APIs, nor the growth in any of the other enabling technologies. In the 2000’s it was Web. Tomorrow will be IoT. Today, it is mobile.

Ok, so What is Swagger? Swagger is a way to define and describe APIs. A language for stating exactly what an API offers. The description language is analogous to Interface Definition Languages going back to Sun’s RPC IDL, Corba IDL, DCE IDL, or SOAP’s WSDL. Many of you reading this won’t recognize any of those names; it doesn’t matter. We don’t use most of those technologies any longer, more importantly we don’t utilize the metaphors those technologies imply: function shipping, remote procedure call, or distributed objects. While moving away from the tight coupling of binary protocols and towards technologies like REST and JSON and XML that enable more loosely-coupled interactions, we still recognize that it’s helpful to be able to formally describe programmable interfaces.

OK, so Swagger is at it’s heart, a way to describe a RESTful API. Many of you are Java developers and may be familiar with Swagger Annotations, which allows you to mark up JAX-RPC server application code, which then allows you to generate a Swagger definition from an implementation. Something like doxygen. This is cool, but is sort of a backwards approach. Getting the description of the API from the implementation is analogous to getting the blueprint for a building by taking pictures of the finished framing. Ideally you’d like to go in the other direction – first build the design (or blueprint, if you will) of the API, and then generate the implementation. My friend and colleague Marsh Gardiner discussed the design-first approach last year.

This is what Swagger can do. How does one produce a Swagger document? Well if you’re an old codger like me, you might resort to using a text editor like emacs and its yaml-mode to hand-code the yaml. But a much easier approach is to use The Swagger Editor.

The API Description is basically “a model” of the API. And with that model, one can do all sorts of interesting things: generate a client-side library in one of various languages. Generate a server-side implementation stub. Generate a test harness. Generate documentation. In fact the Swagger project has had a doc-gen capability, named swagger-ui, since the early days of the project.

So what’s the upshot? The result of better enabling tooling around APIs, tooling including Swagger Editor and Swagger UI, as well as an API management layer as provided by Apigee Edge (Disclaimer! I work for Apigee!), means that it is easier for companies to expose capabilities as easy-to-consume APIs, and that it is easier for developers to code against those APIs to build compelling experiences that run on mobile devices. So I’m pretty excited about the new tooling, and I am even more excited about the integration we will soon see between these new modeling tools and the existing API Management tools already available.

Good stuff!



Developer , , ,

Loving the simple API Design Guidelines from GoCardless

See here.

I like this for several reasons:

  • I like the simplicity and clarity of the guidelines.
  • I agree with all of their guidelines; nothing feels controversial there. Such as: Use JSON, and pretty print it. Be explicit with error messages. Use plural nouns for containers. Etc.
  • I like the fact that it is open sourced for the world to see, share and fork.

ps: My employer, Apigee, is still looking to hire SEs, and other API geeks.



Developer , ,

Oregon sues Oracle over app delivery

screenshot-20140822-155853

Fortune Magazine is reporting that the US State of Oregon is suing Oracle for $200 million, alleging fraud for Oracle’s role in building the state’s failed health insurance exchange.

Ouch!



Business ,

Uber aims to be a platform

You may think of Uber as a disruptive player in the hire-car business. They offer a service similar to taxis, but enabled with an app experience that riders really appreciate. The hailing and pay-by-phone experience is something that I personally love. I love knowing where the driver is, how long it’ll take to arrive, the ease of paying, and so on.

But now Uber is launching an API. They’re aware that disruption is not simply something they dish out to others, but that they are also subject to disruption. They cannot afford to stand still.

Uber has a key asset – a network of drivers available on a for-hire basis. By exposing that asset programmatically via an API, Uber turns itself from simply a taxi service with an app, into a people-and-goods delivery platform upon which other companies can build their businesses. Pharmacies are a key potential partner – think of Prescription delivery services for people with limited mobility. Uber can act as a personalized delivery service for any high-value retail good.

Or think of personal concierge services – what if you could build an app to request a car to any location on behalf of a VIP or a person you’re trying to impress?

Uber have announced 11 partners at the launch of their public API. Obviously the market is interested in building new businesses or expanding existing businesses in partnership with them.

The beautiful thing about APIs is that any business can expose their capabilities programmatically to transform into a “platform”. That means greater reach, more partnerships, lower cost of business development, better return on assets.

Think back: this is exactly the kind of nirvana we in the industry were envisioning, 15 years ago, when we created SOAP and all the WS-* specifications. But we went too far out on the complexity-vs-value spectrum. It turns out the WS-SecureConversation spec was not the key concept that would enable flexible business partnerships. We now realize that simplicity of design and ease of programmability are the keys to unlock the possibilities in this domain. I’m so glad that time has arrived!

What’s the basis for your platform?



Strategy , , ,