APISpark 2.0 released

March 11, 2014

Posted by Swann Vichot in : APISpark, Restlet General - no comment

First of all we are very happy to announce that our website has undergone a major redesign!

It’s clearer, easier to navigate and we’ve merged and so you can find everything on the same site!

Screen Shot 2014-03-06 at 5.34.01 PM

Concerning the platform itself, a great deal of work has gone towards stabilizing the console.

Since last release in December, there have been numerous bug fixes (more than 100) in addition to several enhancements to keep our beta testers buzzing! Below is a detailed summary:

New features

  • API firewall (preview)
    • introduced IP addresses filtering with white & black lists
    • default CORS support to allow cross origin browser access
    • coming next: rate limitation
  • GitHub wrapper (preview)
    • provides a File Store wrapper backed by GitHub repositories
    • coming next: subfolders, account pairing and branch selection



  • Entity Store browser
    • auto-generated fields are hidden at creation and update time
    • 1-1 and 1-n cardinalities are supported for both primitive properties and properties referencing other entities
    • bug fixes for default values, duplicate properties and date entry (MM/dd/yyyy format enforced)

add entity from browser5

  • Error pages:
    • more explicit messages displayed
    • redirection after re-authentication in case of session expiration
  • Domain selection:
    • clearer error message in case of unavailability or forbidden characters

error messages

  • Entity Store:
    • added min/max values, auto-generated and nullable properties
    • default primary key was renamed to “id” (was “_id” before)
    • new auto-generated properties (creator, lastUpdated, created)
    • properties constraints now enforced at insertion and update time

new entity properties3

  • Web API:
    • fixed date entry issue (MM/dd/yyyy format enforced)
    • improved properties ordering for representation samples

Thank you to all our beta testers who have taken the time to give us feedback and who have supported us from the start. We hope you enjoy this new version of APISpark. Let us know what you think by sending us an email or by using the Help Desk.

APISpark 2.1 sneak peek?

For the next release, the console will be following in the footsteps of the web site start getting a complete makeover. Stay tuned!

Stay in Touch:

twitter icon orange small     google+ icon orange small     slideshare icon orange small     wordpress icon orange small     linkedin icon orange small

Restlet Framework 2.1.7 and 2.2 RC1 released

February 13, 2014

Posted by Swann Vichot in : Restlet Releases, Uncategorized - no comment

We are happy to release two new Restlet Framework versions: 2.2 RC1 and 2.1.7, quickly moving forward towards version 2.2.0 and beginning work on the 3.0 branch. Check out the updated road map for details.

Don’t forget to download A Field Guide to Web APIs from Kin Lane, API Evangelist. It’s a comprehensive developer guide, covering history of web APIs, technology used, cloud trends etc. If you want a preview before downloading the full guide, check out our previous blog post.

What’s new?

2.1 branch (stable)

Since announcing the release of the 2.1.4, we fixed several issues including:

  • XML External Entity injection security fix (please read our technical note and upgrade)
  • Generation of HTML representation of a WADL document
  • Complete the content-type header with the right boundary parameter value when using multipart representations
  • Status reason phrase set by the Jetty connector
  • Service-Component header missing in for Servlet extension in OSGi edition
  • OData not passing null when property not marked nullable
  • EncoderService exposes lists of ignored and accepted media types
  • Base64 characters padding to encoded MD5 hash before decoding.

In terms of enhancements, we added:

  • Support of nowrap “deflater” (support of GZIP compatible compression)
  • Ability to override Accept-encoding header values
  • WritableSocketChannel write loop to ensure all data has been written

Logo Restlet Framework

2.2 branch (testing)

In addition to the 2.1 branch fixes, we also solved six bugs including:

  • Declaration of Gson’s maven artifact identifier
  • Android ICS and HttpUrlConnectionCall.getResponseHeaders
  • The @Patch annotation was ignored

As well as numerous enhancements:

  • Updated over 25 dependencies (Jetty, Apache, MongoDB, etc.)
  • Added a Message#bufferEntity() method
  • Moved BufferingRepresentation from Engine to org.restlet.representation package
  • Added client support for HTTP OAuth MAC authentication
  • Added Javadocs artefacts for Maven repository
  • Added Thymeleaf templating extension
  • Improved ServerServlet.createComponent()
  • Added Swagger extension (only JAX-RS API support for now)

And made the following changes to Restlet Core (API and Engine):

  • Added new internal HTTP/HTTPS server connectors based on the package available in JDK 6
  • Moved HTTP/HTTPS/FTP client connectors into the core org.restlet module ( package) as the new internal client connectors
  • Moved NIO-based internal connector to new org.restlet.ext.nio extension. Marked as “developer preview” state.
  • Moved org.restlet.ext.ssl into core org.restlet.engine.ssl package except classes related to the jSSLutils library now part of new org.restlet.ext.jsslutils extension and for CertificateAuthenticator class now in
  • Deprecated MediaType#APPLICATION_RDF_TURTLE and added TEXT_TURTLE constant

Recent contributors

  • Alvaro Munoz
  • Andy Dennie
  • Bobby Sawhney
  • Carl J. Mosca
  • David Roussel
  • Grzegorz Godlewski
  • Ioan Lupu
  • Jason Guild
  • Luke Adams
  • Peter Ansell
  • Ralph van Etten
  • Tal Liron
  • Xiaoping Feng

Thanks to all others who helped us in various ways.

Additional resources

Changes log:

Download links:

Learn more:
Tutorial, User guide, Javadocs
A Field Guide to Web APIs by Kin Lane

For more updates:
Follow Restlet Framework on Twitter (@restlet_org)

A Field Guide to Web APIs by Kin Lane

February 11, 2014

Posted by Swann Vichot in : APISpark, General, Restlet General - no comment

Kin Lane, API Evanglist, has been in the technology space for over 20 years and wants to help the world understand the great value and potential that is growing in the web API market.

To do so, he teamed up with GigaOM Research and Restlet to write a comprehensive guide to web APIs. Follow Kin on Twitter: @kinlane

Kin Lane, API Evangelist

Following are the summary and a few extracts of the guide. Download the full electronic version here: A Field Guide to Web APIs.

  • Executive Summary
  • What are APIs used for?
  • Why are web APIs different?
  • History of web APIs
  • What technology goes into an API?
  • Deploying your web API
  • Established practices for managing APIs
  • Marketing and API evangelism
  • The Future of Web APIs
  • Cloud Trends
  • Key takeaways

“A new breed of web API has emerged, delivering a vision of a lightweight, low-cost approach to connect devices and allowing applications to exchange data efficiently.”

“The most popular approach to delivering web APIs is REpresentational State Transfer (REST). This approach to API design takes advantage of the same internet mechanisms used to view regular web pages, so it has the advantage of faster implementations and is easier for developers to understand and put to use.”

“A company with resources to deploy and maintain websites can easily research and deploy APIs using the growing variety of available API frameworks such as Restlet [...]“.

GigaOM Logo

“A handful of solutions such as APISpark [...] have emerged in the past year to provide API deployment as a service. They connect to existing or new data sources and then generate web APIs complete with a portal and management tools.”

“Cloud API deployment from common data sources is making API deployment accessible to the masses, enabling API deployment of numerous resources easier for developers while making API deployment something even a nondeveloper can understand.”

Restlet Logo

“PaaS, which is one of the fastest-growing aspects of web and mobile development, provides an API-driven suite of tools that provides essential services for developers in a pay-as-you-go approach. This is the next generation of business utilities designed for developer consumption.”

Download the full electronic version here: A Field Guide to Web APIs.

The research report was underwritten by Restlet.

APISpark public beta launched

December 23, 2013

Posted by Swann Vichot in : APISpark, General, Restlet General - no comment

The APISpark team is happy to report the launch of its public beta. The access is no longer restricted and you can sign up today to create your first API on!

The launch was announced during the APIDays Conference (December 4th – 5th 2013) in Paris and feedback so far has been very encouraging. See this report on our participation to the event.


When signing up for APISpark, you will be able to follow tutorials to get you started and become familiar with the platform.

If you encounter any issue, you can let us know via the Help Desk so we can look into it and fix it. By doing so, you will be contributing to the successful development of APISpark and for that, we thank you.

New features and enhancements

Since our last release, we have made the following changes:

HTTPS endpoints for subdomains
We had previously announced HTTPS access to both the APISpark public web site and the console. Well, now you can also deploy your APIs safely as we have added HTTPS endpoints for all domains.

HTTPS endpoints

We also fixed SSL certificates to prevent unecessary browser warnings.

Quick export of Data Stores as Web APIs

Previously, creating a regular CRUD web API from an entity store required several steps including:

  • switching from the entity store to the dashboard
  • creating a new custom web API
  • importing the entity store from the API via the settings tab
  • launching the feature adding the resources from the store
  • switching to the API overview to see the new API contract

While this only takes five minutes to achieve, we realized that these steps are not very intuitive for new users. This is where the new API export feature really helps.

Quick export

Instead of five steps, you can now do all this in a single step! We have added an “Export custom API” action to the actions menu of entity stores (and also to file stores).

That action displays a special Web API creation wizard, right inside the store page. Once you fill out all the info and click on “Create”, you directly see the API overview of the new API.

Global ordering review

In this version, we also revamped the ordering of items displayed in the console, such as the properties of an entity and the list of resources of an API.

We now guarantee that their visual order will be maintained and will be logical as it can have some impact at runtime, for example on routing of API calls.


As you can see above, you can easily drag & drop a resource to change its order as well.

Misc changes

To ensure an efficient recovery plan, your structured data (store via the default entity stores) is now replicated 3 times in 2 regions (USA and Europe).

The next step for us it now to also replicate the web APIs and provide a cross-region deployment and availability of those APIs.

Finally, we also fixed about 18 bugs in this new release.

From all the Restlet team, we wish you Happy Holidays!

Swann Vichot

News coverage:

APISpark at APIdays Paris 2013

December 17, 2013

Posted by Swann Vichot in : APISpark, General, Restlet General - no comment

What an event!

First of all, let me just say that as a newbie to the API arena, I found this conference to be full of valuable information and extremely rich in content.

Api Days 2013 Paris.

There were many industry-leading speakers. Jérôme Louvel, CEO of Restlet, was a speaker for the first day of the event and had wonderful turnout for his speech “Web APIs, the New Language Frontier”. He also announced the public beta of APISpark, more details are coming in another blog post!

Api Days 2013 Paris.

If you missed it or are interested in reviewing the slides again, you can find them here:

Web APIs, the New Language Frontier from Restlet

The second and last day was a little less restless (pun intended – excuse me, as a non-tech person, this is probably the only one accessible to me!) Steve Sfartz, VP of Engineering at Restlet, gave his speech “How to Build your Web API”. There weren’t many developers in the room but we did get visits at our booth after the presentation and got valuable feedback and a very interesting use case to explore – thanks to Wenting Sun of Nanyang Technological University of Singapore.

Here are Steve and Wenting, using the APISpark platform on an iPad to build and study her API needs.

ApiDays Paris 2013

As a Gold Sponsor we were really happy with the way things were set up. There were some stimulating talks and positive energy throughout. Overall, a great success!

On a complete side note, breakfast was delicious and very français.

Thank you to Webshell and FaberNovel for organizing this great event.


by Swann Vichot
Marketing Assistant at Restlet

Thank you to APIdays and François Tancré for the photos.


Restlet gets funding to accelerate APISpark growth!

November 13, 2013

Posted by Jerome Louvel in : APISpark, Restlet General, Uncategorized - no comment

All the Restlet team is excited to share some great news today. We are announcing a large seed funding round, our company Board and new team members!

Open Roots

When I launched the Restlet open source project on TheServerSide in 2005 as a consultant, I didn’t know how far this could lead me, but I knew Restlet Framework was the first of its kind, true to the principles of the Web (the REST architecture style published in 2000).

It changed the way Java developers can build and consume web applications & sites, without forcing previous paradigms such as RPC and MVC into a web “pipe” or artificial separating web server (think Servlet) and web client (think Apache HTTP client) technologies.

From Noelios to Restlet

After many  iterations, we reached version 1.0 and transformed Noelios as a company in 2008 with my co-founder Thierry Boileau to offer professional services. This allowed us to fund the R&D effort on Restlet, dedicate time to the writing of ‘Restlet in Action’ book and refine our ROA/D methodology.

In 2010, our technology was getting mature with 6 consistent editions supported (Android, GWT, GAE, Java SE/EE, OSGi) and the web API and cloud computing market were warming up. We started thinking about the next 5 years, now that REST and web APIs were about to become mainstream.

What was our next challenge?

APISpark, a PaaS for Web APIs

We decided to build a product around our open core that would help developers create and use the hundreds of thousands of web APIs expected in the coming years.

Our new mission was to democratize REST and web APIs for the broader developers community, beyond our community of API experts and Java engineers. 

0111_apiSpark_Logo (wordpress)

APISpark was born from the idea that creating APIs should be as simple as creating blogs on a couple of minutes, a simple browser and a fraction of the “Do It Yourself” cost. APISpark brings together the IDE, hosting and management aspects into an unified Platform as a Service (PaaS) for APIs.

We also renamed the company to Restlet and changed our business model to leverage the cloud economics. APISpark is a freemium service that any developer can use free to get started. See our pricing page for details.

Funding, Board and Team

In order to successfully pivot, we needed funding, help from experienced entrepreneurs and a stronger presence in Silicon Valley. Today, we are happy to announce that we have closed a $2M seed round from two European VCs (SIPAREX and CapDecisif Management) and a few individual investors. 

We are also delighted to welcome our Board members: Bertrand Diard, co-founder and VP Strategy of Talend, Reza Malekzadeh, VP Business of Cumulus Networks and Matthieu Hug, CEO of Fujitsu RunMyProcess, along with our investor representatives. See our Board page for details.

In addition, we are welcoming Stève Sfartz as a third co-founder and VP Engineering. His strong experience in online service operations and R&D management will help us grow and structure our engineering team. Olfa Zorgati is also joining our team as our new CFO, based in the Silicon Valley where I’m moving as well. See our Team page for details.

We have also posted our first job descriptions for open positions immediately available in our engineering team.


I’m excited to pursue Restlet adventure and would like to thank all contributors to the Restlet Framework, early testers of APISpark, company advisors, numerous partners and customers who helped us getting so far!

Jérôme Louvel
Restlet, CEO

News coverage

APISpark integrates with existing data stores

September 23, 2013

Posted by Jerome Louvel in : APISpark, Restlet General, Uncategorized - no comment

Summer has been hot for the APISpark team. We improved the overall platform stability, fixed more than 50 issues, and added many new features. Today, we are happy to roll out a new release in production!

Re-expose your backend as web APIs

Today, mobile and HTML 5 applications are connected. These applications rely on a cloud backend to store user and shared data. Beside the lengthy Do It Yourself (DIY) approach, many developers prefer to rely on BaaS (Backend as a Service) providers such as Parse, StackMob and Firebase.

Several developers came to us asking for an easy and flexible way to re-expose data contained in their mobile backends. Moreover, these developers want to add business value to their data through custom, domain specific Web APIs. In other words, the built-in Web API provided for free by their traditional BaaS lacks flexibility and extensibility to suit their needs.

This is where APISpark’s new “Entity Store Wrappers” come into play, providing an easy way to expose one or multiple custom API on top of an existing BaaS. Click above to follow the APISpark tutorial for each wrapper.

Turn your Google Spreadsheets into APIs

In addition, we have worked on an integration with Google Spreadsheet. This brand new wrapper helps you expose structured data while keeping the ability to edit them using your traditional spreadsheet UI. We strongly believe that this wrapper will suit a large set of user needs and specifically Open Data use cases.

Expose your Database in the Cloud as APIs

To finish with, we also added a wrapper for any JDBC data sources, such as classic relational databases as explained in this tutorial. We have plans for additional entity wrappers, so please give us feedback on the integration models you would like to see work on.

Serve your existing files stored in AWS S3

Even though APISpark already comes with built-in file stores, internally backed by AWS S3, some users want to re-expose files stored in their own AWS S3 account. Thanks to the new File Store wrapper, APISpark supports this scenario as explained in this tutorial.

Our plan is to incrementally add new wrappers. Google Drive comes next on our list.

Many more enhancements!

In addition to these new wrappers, we have added many features based on your feed-back including:

  • GWT and Android client SDKs

  • Source code export for your web APIs (based on the open source Restlet Framework)

  • Support for GitHub login and more providers

  • Subscription management (plan selection, payment, billing)

  • Deployment region can now be selected (US-West or EU-West right now)

  • Enhanced dashboard filters, full-text capabilities, instant search

  • Terms of Use and Privacy Policy pages

Next steps

If you don’t have an APISpark account yet, we invite you to sign up for the beta. And if you can’t  wait to discover APISpark, walk through our first tutorial. If you want to know what is coming next, please check our updated public roadmap.

Thanks for all your feed-back. We can’t wait to seeing what you will build with APISpark!

Restlet Framework 2.1.4 and 2.2 M5 released

September 18, 2013

Posted by Jerome Louvel in : Restlet Releases, Uncategorized - no comment

After a big push on the APISpark front during the summer, it was time to release new versions of the Restlet Framework.

2.1 branch (stable)

Since last announcement, we released both versions 2.1.3 and 2.1.4, fixing ten issues including:

  • Security issue with JavaBeans object de-serialization mechanism, now been disabled by default
  • HTTP status error in AJAX with old IE versions
  • Extension headers are now copied from JAX-RS API response to Restlet API response
  • JSON extension building has been fixed for GWT edition
  • Infinite loop in Feed class of Atom extension
  • Date concurrency issue due to broken caching attempts

Logo Restlet Framework

2.2 branch (testing)

In addition, here are the main changes made to the 2.2 branch:

  • Added GSON extension, supporting Google’s serialization library between Java and JSON
  • OAuth 2.0 extension upgraded to support final OAuth 2.0 specification
  • All bugs fixes in versions 2.1.3 and  2.1.4

Recent contributors

  • Abraham Kang
  • Alvaro Munoz
  • David Jorm
  • Dinis Cruz
  • Koen Maes
  • Loïc Oudot
  • Mark Kharitonov
  • Neal Mi
  • Robert Fischer
  • Shotaro Uchida
  • Tim Peierls

Thanks to all others who helped us in various ways.

Additional resources

Changes log:

Download links:

New release of APISpark rolled out

May 21, 2013

Posted by Jerome Louvel in : APISpark, Restlet General - no comment

Today we are rolling out a third release of APISpark beta. The previous releases are described in blog posts #1 and #2. If you want an access to the beta, please share your interest in APISpark on Twitter (@apispark).

Also, you might want to read our latest “How much REST should your web API get?” blog post and the following discussion. Now, let’s continue with an overview of the changes released in production today!

Complex entities & representations

First, we added support for one of the most requested features: the ability to define and persist relationships between entities, including association, aggregation and composition.

We also added support for abstract entities and ensured that when automatically creating an API from an entity store via the import wizard, we expose complex entities via matching complex representations.


The Java and JavaScript client SDKs, the offline HTML and PDF documentations have also been updated to either use or describe complex representations. We will soon update the iOS client SDK as well.

API templates and contracts

APISpark can not only create a web API from scratch or from an imported entity store, it can also let you create a web API based on an API template. You can think of them as blog themes on that lets you create your own custom blog in just seconds.

New API templates can be created from scratch or from a complete API that has been already deployed and tested. See the “Extract template” action in the drop-down menu below.


Those templates then appear in your dashboard, with an icon surrounded by a thick orange border as illustrated below and can be reused to create new APIs.


Like complete web APIs, public templates can be promoted to APISpark Catalog. Instances can then be created in seconds, each having its own runtime, including dedicated HTTP endpoints, members or analytics data.

The API contract and implementation are not cloned and remain controlled by the origin template. A similar feature just for API contracts is also provided, only including the visible aspects of a web API including the list of resources, methods, representations and client SDKs.


API contracts have several benefits for API users including easy switching from one API provider to another, or calling multiple APIs supporting the same contract but exposing different data.

Enhanced API implementation

When you deploy an API with APISpark, we internally generate some source code that has the Restlet Framework as main dependency. This source code is then compiled and packaged before being hosted by APISpark.

Restlet Framework

We try to generate this code exactly like a Restlet Framework developer would have written it. This means that your web APIs created by APISpark can be as performant in production as those written by hand. APISpark doesn’t interpret web APIs at runtime, but execute them at full byte code speed.

In this release, we have enhanced the implementation layer of APIs with:

  • added support for multiple actions

  • implemented action types (call imported API / call imported store / return response)

  • streamlined generated mapping code for speedier execution time

  • other APIs can now be imported and invoked (composite APIs)

Upgraded to Cassandra 1.2

APISpark enable you to store structured data via local entity stores, and later expose them through one or multiple web APIs.

In order to support efficient multi-tenant hosting, we rely on Apache Cassandra. Even though this technology choice is not directly visible to APISpark developers, it is key for us to provide:

  • potentially unlimited entity store sizes, spreading across machine clusters

  • highly-available entity stores thanks to continuous replication across mutiple machines

  • live entity store schema modifications without having to restart the database

  • flexible replication schemes including multi-region deployments

Cassandra logo

In this new release of APISpark, we have refactored our persistence layer, upgrading to version 1.2 of Cassandra which brings new features: 

  • better multi-tenant performance for concurrent schema changes on entity stores

  • better scalability and fail-over behavior thanks to virtual nodes

  • speadier access thanks to new native driver

  • support for repeating properties thanks to the new collections feature in CQL3

Even though you don’t have a direct access to the low-level Cassandra database powering APISpark entity store, we want to let you know that we use the best-of-breed cloud database technology to power web APIs hosted on APISpark.

We are also working on entity store wrappers for data living outside APISpark platform to let you reexpose them through proper web APIs. Stay tuned for the next release of APISpark for more information about this feature.

Improved stability

In addition, we have started to roll-out intra-region fail-over support to ensure that your APIs hosted by APISpark are highly available in case of hardware failure. Currently APISpark runs from the Northen California data center of Amazon Web Services.


The next step is to roll-out the multi-region deployment with a second data center in Virginia so that in case a complete AWS region goes down (which is very rare but already occured in the past), your web API can still run out of the other region in a way that is almost transparent to your API users, beside the increased network latency.

Finally, we fixed several issues:

  • URI path variables are now declared when adding resources from imported entity stores

  • Adding multiple sources selection in the Mapping panel

  • Adding mapping support for path variables and query parameters when calling an API

  • Fixed API contract filtering on the dashboard

Getting started

If you want to see how creating, hosting and using web APIs looks like with APISpark, we recommend our first tutorial. 

How much REST should your web API get?

May 2, 2013

Posted by Jerome Louvel in : HTTP, REST, Restlet General, Semantic Web, Uncategorized - no comment

There is an ongoing debate regarding the proper way to design web APIs. This is often related to the following terms:

Recently, I read “Getting hyper about hypermedia APIs“, a blog post from David H. Hansson (Rails’s creator). Looking at both the quality of his arguments and the defensiveness of the readers’ comments, he clearly hit a nerve.

To understand why this is important, let’s compare the REST and Web API architecture styles in tension.

REST style, as defined by Roy T. Fielding

REST was formally defined in 2000 for systems that are both distributed and driven by hypermedia interactions with humans.

Fully embracing it requires you to respect the 5 mandatory constraints (plus an optional one), as described below.

Note that this summary contains large excerpts from Roy T. Fielding’s thesis:

1 – Client-Server constraint

  • separation of concerns
  • client = user interface concerns (
  • better UI portability across platforms)
  • server = data storage concerns (more
  • simple and scalable implementations)
  • independent evolution of clients and servers at Internet scale

2 – Stateless constraint

  • each client request must contain all the info necessary for the server to respond
  • session state is kept entirely on the client

3 – Cache constraint

  • allow client to reuse response data in a controlled manner
  • support intermediaries such as proxies and shared caches

4 – Uniform Interface constraint

  • central and unique feature of REST
  • less efficient than a customized interface due to the standardization overhead
  • efficient for large-grain hypermedia data transfers
  • not optimal for other forms of architectural interaction
  • sub-constraints
    • identification of resources via URIs
    • manipulation of resources through representations (HTML hyperlinks, forms or JavaScript/AJAX style)
    • self-descriptive messages
    • hypermedia as the engine of application state (HATEOAS)

5 – Layered System constraint

  • each component only knows about the immediate component/layer it is interacting with
  • favor intermediary components (load-balancers, reverse proxies, shared caches)
  • can add overhead and latency
  • gives pipe-and-filter benefits (combined with Uniform Interface constraint)

6 – Code on demand constraint [optional]

  • client component doesn’t know how to process the resources it has access to
  • code representing this know-how is retrieved by the client and executed locally
  • dynamic feature addition to deployed clients
  • improved extensibility and configurability
  • better user-perceived performance and flexibility
  • improved server scalability (offload work to the client)
  • lack of visibility requires client to trust the server (security sandboxing required)

In addition to these constraints, REST also defines as a set of architectural elements that directly abstract the semantics of the HTTP application protocol:

  • data elements
    • resource (conceptual target)
    • resource identifier (typically an URI)
    • representation (HTML document, bitmap image)
    • representation metadata (media type, modification date)
    • resource metadata (allowed methods, alternates)
    • control data (content negotiation, conditional requests, compression)
  • connectors (client, server, resolver, tunnel)
  • components (origin server, user agent, gateway, proxy)

Finally, REST defines three views that illustrates the style including the process, connector and data view. The last one illustrates what a REST client can be:

  • primarily an hypermedia browser, including ability to do incremental rendering
  • an automated robot performing information retrieval for an indexing service
  • a personal agent looking for data that matches certain criteria
  • a maintenance spider busy patrolling the information for broken references or modified content

End of excerpts.

The web of documents and browsers, as we know it, is the best example of the REST style in action. This is logical as REST was inferred from the earlier Web architecture during the specification of HTTP version 1.1.

However, looking at Roy T. Fielding recurrent reactions regarding the improper usage of “REST” as a buzzword, it is time to question whether the REST style can be or should be used when building regular Web APIs.

Web API style, as practiced today

Web APIs are designed for systems that are both distributed and driven by machine-to-machine interactions.

This Web API style is the result of the evolution of pragmatic development practices since 2000, starting with the emergence of Web Services (WS-* and *-RPC) and then the strong influence of the REST style towards more simplification and proper usage of HTTP as an application level protocol rather than a lower-level transport protocol.

Let’s attempt to formalize this style in a way similar to REST. Embracing it requires you to respect the 6 constraints described below:

1 – Client-Server constraint

  • separation of concerns
  • client = program with varying concerns (maximum reusability needs)
  • server = data or logic accessibility concerns (build ecosystems of innovation)
  • independent evolution of clients and servers at Application scale
  • significant difference from REST

2 – Stateless constraint

  • identical to REST

3 – Cache constraint

  • identical to REST

4 – Custom Interface constraint

  • predefined set of resources including identifiers and representations
    • cool URIs that don’t change
    • developers friendly URI naming based on conventions
  • more efficient than dynamic discovery
  • requires coordination between clients and servers when changes are deployed
    • based on explicit versionning
  • efficient for both small-grain mobile data transfers as well as large-grain data transfers
    • based on parameterized resources and content negotiation
  • not optimal for other forms of architectural interaction
  • sub-constraints
    • identification of resources via URIs (identical to REST)
    • manipulation of resources through low-level HTTP clients (using for example raw JSON or XML representations)
    • manipulation of resources through high-level client SDKs (for major programming environments) when available
    • developer documentation to help with understanding of the interface
  • significant difference from REST

5 – Layered System constraint

  • identical to REST

6 – Mobility constraint

  • intermittent Internet connectivity
    • potentially unavailable for a long time
    • requires an off-line application mode
  • expansive Internet connectivity
    • typical mobile data plans have data limits per months
    • ability to switch to less expansive radio networks when available
    • highly dependent on actual client location
  • irregular bandwidth (potentially very low)
    • adjust media size dynamically
  • irregular latency (potential very high)
    • aggressively use cache (by default)
    • synchronize cache when possible
  • not present in REST

As you can see the Web API style has been very much influenced by REST and share many of its constraints. This influence over 10 years has resulted in key simplifications compared to the original RPC style to make it more aligned with the core Web concepts such as resources, URIs, representations and the HTTP protocol.

REST and Web API styles are web brothers

There is no reason to oppose both styles as they are not solving the same problems, even though they are both deeply connected with the Web. The figure below represents their main differences.


Both styles are complementary and can be used together, for example when building a single page web application where the main HTML is loaded through a regular web page (REST style), including some JavaScript (code on demand constraint). This code is then interpreted by the web browser to make AJAX calls back to a Web API, exchanging predefined JSON representations.

Let’s also mention hyperdata as a second form of hypermedia with hypertext, that also offers a comprehensive application of REST. This is the world of the Semantic Web and especially the pragmatic Linked Data movement based on RDF and related media types such as Turtle, JSON-LD or HAL.

In other situations, where the client isn’t a web browser but a native mobile app, a connected device or a program written by a partner to integrate your web site with their own, you only rely on the Web API style, which is fine again. Let’s now step back and see where these new forms of web architectures will lead us.

Building cross-device web sites

By combining the power of REST (the web of documents) and of Web APIs (the programmable web), we can build a new generation of web sites that are inherently cross-device. as illustrated below.

Cross-device web sites

Those web sites let organizations of all sizes provide a pervasive and contextual access to their information and services, to both customers, employees and partners via potentially any kind of machine.

I will wrote more about cross-device web sites in future posts as they help understand the strategic value brought by Web APIs in this new era of mobility.