How to identify objects as REST Resources

How to identify objects as REST Resources


Assuming the reader has an idea of the REST design philosophy, rampant confusion exists on what is exactly a resource.  Much debate exists on how to identify and/or classify Internet HTTP objects as REST resources.  A resource is the data end point of a URI (e.g.,  Data is emphasized because REST resources should be a stateless data representations that can be bookmarked.  It’s important to understand this design philosophy when creating a REST resource.  This idiom is often ignored and puts a REST design in significant peril.

I have also seen many SOAP implementations shoe-horned into REST which only leads to abstruse REST structure.

So how are these resources manipulated?  REST resources are manipulated in 2 ways, through the HTTP verbs (PUT=UPDATE, POST=ADD, GET=RETRIEVE, DELETE=DELETE) and custom REST objects called components.

Components act upon Resources.  (What Roy Fielding calls components some people call controllers. REST components perform actions on a resource by using a representation to capture the current or intended state of that resource and transferring that representation between components.) This is an important concept to understand, because it is the foundation of good REST design.

A good REST design will define data elements as the resources, use PUT, POST, GET and DELETE to manipulate the data.

An easy way to design REST is to look at the landscape and divide your nouns and verbs.  The nouns are your resources and the verbs should fit under PUT, POST, GET and DELETE and act as your controllers or actions verbs.  If you can remember this simple design constraint, the limitation will assist in creating a decent REST design.

Booker Showers

Better Orchestration Through Folder Structure

Better Orchestration Through Folder Structure

Organizing resources into an appropriate structure is a major struggle for most implementors.  Unorganized resources makes it difficult to scale.  In addition, confusing folder usage as taxonomy instead of data usage places an unnecessary burden on a consumer of a resource.  Maximum orchestration can only be achieved through proper semantics.

A folder should contains all the resources that belong to the current data structure. The folder includes all files, resources and/or business data necessary to process a request.

Most of the time, there is only one data resource. Sometimes, there may be more than one data resource for the same composite resource (e.g., one for http and another on https).

A project folder should contain resources attached to a project. The composite resource may be divided into corresponding systems and inserted into a specific folder called by an orchestrator.

The specific folder name under the system folder contains all resources belonging to the current implementation. The specific folder includes all files and resources. For example, the folder will contain the XSLT files, the XSD files, WADL, and/or WSDL files used to call a resource.

An Infrastructure folder should contain all resources that are not specific to a particular project or implementation. The Infrastructure folder includes the XSD files, Query files, shared function files, and the WSDL file used to implement a generic service.

Booker Showers

REST Conductor

The REST Conductor

Improper REST usage is difficult to scale and can reduce developer adoption.  The following points are important to consider  when taking on the role as The REST Conductor.

REST is an ideal solution for data collections and underlying data:

  • For all data resources the common HTTP 1/1 verbs are used to specify the action taken on the resources GET, PUT POST and DELETE.
  • All resource names should be plural nouns.
  • The resource path should be resource restrictive. If a word is in the path of the URI, the word should return a value.
  • Collections should be returned for the plural connotation, e.g. “Devices.”
  • To refer to a specific resource, the ID of the resource should be used, e.g. “/Devices/4893”.
  • An operation is idempotent if a sequence of two or more of the same operations results in the same state or result. (If you call an operation more than once you should receive the same result.) According to the HTTP 1.1 specification, GET, HEAD, PUT, and DELETE are idempotent, while POST is not. Multiple attempts to PUT (update) data to a URL results in the same resource state returned, which is the same as a single attempt to PUT data to the URL. However, the same cannot be said of a POST request as the state of the resource may change.)
  • The following is recommended for REST operations:
    • Create = PUT if and only if you are sending the full content of the specified resource (URL).
    • Create = POST if and only if you are sending a command to the server to create a subordinate of the specified resource, using some server-side algorithm.
    • Retrieve = GET (must be side effect free).
    • Update = PUT if and only if you are updating the full content of the specified resource.
    • Update = POST if and only if you are requesting the server to update one or more subordinates of the specified resource.
    • Delete = DELETE.
  • REST resources may put hyperlinks within URI representation to enable clients to drill down for more information, and/or to obtain related information. Moreover, REST resources may gradually reveal data rather than in a single response document by providing hyperlinks to obtain more details.

Booker Showers

Service Mediation

Understanding Service Mediation


Mediation is a metaphor used to describe brokering service capabilities.  A skilled developer can build a mediation model on top of any provider’s software to deliver services in a controlled and efficient manner.

What problem does mediation solve?

Customers want access to company services. When customers sign up for a service via a website the customer does not like to wait to use the service.  Additionally, when a customer signs up for several services at once they usually want immediate access to the services.

Suppose the following services are provided by a company⎯audio streaming, online billing, content downloading, self service support, and 3rd party apps.  Each of the services has its own infrastructure and are managed by different departments.  How can  customers gain access to multiple services immediately after they sign up?  Service Mediation.

Service mediation is the mechanism used to stitch together various system services and present to a customer one unified service.

However, service mediation is not limited to internal infrastructure type services accessible to customers. Service mediation also applies to REST resources a company wants to make available to internal and external developers.

Understanding Service Mediation

Services are composite functions built by combining multiple Factory Assistants.  A composite service consists of services drawn from several different factories. The components may be individual services, functions from within other applications, or entire systems.

Mediator provides centralized Business Support by integrating process flows and business logic. Main also provides synergy across services, users, and subscriptions. Moreover, this synergy is dynamically created, configured, and provisioned by using a set of profile definitions and policies.

Sentry is the access point. Software on this layer provides security to USM capabilities from a user interface.

Factory assistants generally provide a set of building blocks common to all services.

Booker Showers

How Resource Restrictive REST URIs Save API Design

How Resource Restrictive REST URIs Save API Design


A common problem with REST is unintentional categorization.  Many creators of REST resources include words in the URL that are unnecessary and provide no value, which lead to problems.  Using unnecessary words (unknowingly) limits the URL’s semantical construction, which leaves less room for resource extension.

Consider a resource restrictive REST URI as a definitive resource. What does the term “resource restrictive” URI mean? Each word in a resource restrictive URI structure should lead to a data source.  For instance, a tree structure that usually has something underneath⎯e.g. /Music/Artists/Albums/Songs, where music contains all music, artists contains musical artists, and the artists albums are another resource one layer deeper.

Music |-Artists |-Albums |-Songs

Every layer reveals an additional concrete resource/s. If I navigate to music, I should see a list of artists. If I navigate to an artist, I should see a list of music belonging to the artist.

Many REST URIs are non-restrictive. In addition, non-restrictive REST URIs provide no value in the URI, only to categorize, not inform.

For example, a REST URI such as /Collection/Music/Received/Songs has no hierarchical value other than categorizing the music as songs received.  Navigating the structure reveals nothing for Collection, Music or Received. Results are only returned when you arrive at songs.  Do you recognize the design flaw?

If the structure type described was the path, where would you add Albums or Artists?

A well, thought-out resource restrictive URI saves future headaches when trying to add additional resources to a hierarchy.  The reason many REST resources only have one resource at the end of a long URI string is because the URI is not well developed. There is nowhere to go after the endpoint.

Booker Showers


Avoid REST Implementation Failure

Avoid REST Implementation Failure

Poorly implemented REST strategies cost companies millions to maintain and decommission. Each failed REST implementation moves REST further down the path to obsolescence.  To avoid REST implementation failure, management and developers must return to REST philosophy basics.

The Representational State Transfer (REST) is an architectural style. REST exploits the benefits and constraints of the web by identifying system restrictive elements that differentiate the design space. Additionally, REST allows the web to stay in harmony with corporate systems.

REST architecture emphasizes system constraints and de-emphasizes creativity or vision. System designers avoid precarious situations by designing, a REST philosophy-based implementation.

Management may want to monetize software assets by exposing internally developed infrastructure as API‘s (Application Programming Interface).  The challenge is to provide an interface that allows developers the creative freedom to generate new applications from a company’s infrastructure elements.

An additional challenge for system architects is to help executive decision makers understand how competitors improperly using REST is not a path to follow.

To use a baker analogy⎯a baker needs different ingredients to bake different kinds of pies. A baker cannot use a pre-baked pie to create other pies.

Ultimately, a better strategy gives a developer some tools and allows the developer to combine those tools with other tools to create a new product. A developer should not be given a finished product and asked to create something new from the finished product.

From a REST architect perspective, the value of resources and controllers comes from thinking in the abstract. Abstract thinking about the parts (instead of the whole) create value for the developers you are trying to attract.

For example, if a telecommunication company wants to gain developer adoption, decision makers would align assets so one asset alone would not accomplish much. However, one asset combined with other assets would create something interesting and viable.

As a developer, you should imagine mixing and matching various resources forming new software products, or incorporating resources into another product. To focus on parts instead of predetermined concepts allows a developer’s imagination to flourish.

When each infrastructure asset independently evolves and gains a consistent interface the benefit to a company lies in monetizing exposed assets to external developers.

Booker Showers


5 Rules For Creating New Versions

I marvel at the debate that takes place about when to create a new version of an API, HTML, or REST resource. In a world where being combative or argumentative is the norm, here is some guidance and ammunition for those looking for sanity when creating a new version.

Parameters Change

Any time a parameter is added or changed on the input or output of a method, the version should be changed. The version change is also a courtesy to developers utilizing the method—hey something was added or changed, so take note.

Methods Change

When a method changes either through a name change, additional functionality, or through deprecation a new version, is necessary.

Location Change

Sometimes it’s necessary to move a method or REST resource to a new location because of an architectural, semantic, categorization, or physical server consideration. When the location of an API method changes, always create a new version and add a warning to the existing API method that the method was moved to a new location, and all future calls should be directed to the new location.

Technology Implementation Change

Technology changes. Frameworks, languages, and new programming techniques are often catalyst for changing the implementation of an API. The changes usually result in a speed increase, better quality, or more functionality. When the technology used to implement a technology changes, it’s a good idea to inform the user via a version change.

Results Change

There may be times when the results returned from a method call are augmented or modified but are not useable. For example, if the results expected are for an address of 50 characters, but the results now include 70 characters and an office suite number the calling programs may not be able to handle the result.

To execute a successful implementation, you must have a practical versioning scheme. Without a versioning strategy, an API and the associated functionality becomes difficult to scale and deploy.

Taliferro IT Consulting Spaces Out

Taliferro IT Consulting Spaces Out

What do you know about the following companies –

Virgin Galactic ✪ Planetary Resources ✪ Altius Space Machines ✪
Blue Marble Exploration ✪ Golden Spike?

The companies mentioned are pioneering suborbital space travel, space exploration, and other nontraditional expeditions. Coming soon is a growing space economy that will require companies to extend information technology to space or miss emerging opportunities for innovation, growth, and profits over the long term.

What better way to expand your information technology infrastructure than to an enterprise space management system. Imagine an infrastructure that manages your retail and/or operations suborbital, in orbit, or eventually on another planet. The next generation in commerce requires companies to develop capabilities that will process data, and convert data into meaningful use in space.

Taliferro’s core competency is mobile strategy. Our expertise and experience can help companies develop enterprise space management systems in the new commercial frontier.

Basic questions we will help your strategic development team explore…

  • How do we prepare our technology to operate in space?
  • How do we move our information technology into space?
  • How do we make our technology adaptable in space?
  • How do we provide space travel services?

We are broadening our landscape from the telecommunication and transportation industries to the next phase of IT evolution that fits perfectly within our mobile strategy expertise:

  • Distributed systems
  • SaaS
  • Cloud computing
  • System optimization

We will help your company develop a clear flight plan that diversifies your IT portfolio for the future.

Taliferro IT Consulting is a proud Bronze Sponsor of the MIT Enterprise Forum NorthWest “Space: Are We There Yet – Tourists, Entrepreneurs, & Miners in Orbit” panel discussion at the Museum of Flight, Seattle on September 16, 2013.

Architectural Musical Chairs – A Software Design Parody

Software Design Parody

Dear Mr. Architect:

Please design and build a house for me. I am not quite sure of what I need, so you should use your discretion.

My house should have between two and forty-five bedrooms. Just make sure the plans are such that the bedrooms can be easily added or deleted. When you bring the blueprints to me, I will make the final decision of what I want. Also, bring me the cost breakdown for each configuration so that I can arbitrarily pick one.

Keep in mind that the house I ultimately choose must cost less than the one I am currently living in. Make sure, however, that you correct all the deficiencies that exist in my current house (the floor of my kitchen vibrates when I walk across it, and the walls don’t have nearly enough insulation).

As you design, also keep in mind that I want to keep yearly maintenance costs as low as possible. This should mean the incorporation of extra-cost features like aluminum, vinyl, or composite siding. (If you choose not to specify aluminum, be prepared to explain your decision in detail.)

Please take care that modern design practices and the latest materials are used in construction of the house, as I want it to be a showplace for the most up-to-date ideas and methods. Be alerted, however, that the kitchen should be designed to accommodate, among other things, my 1952 Gibson refrigerator.

To insure that you are building the correct house for our entire family, make certain that you contact each of our children, and also our in-laws. My mother-in-law will have very strong feelings about how the house should be designed, since she visits us at least once a year. Make sure that you weigh all of these options carefully and come to the right decision. I, however, retain the right to overrule any choices that you make.

Please don’t bother me with small details right now. Your job is to develop the overall plans for the house: get the big picture. At this time, for example, it is not appropriate to be choosing the color of the carpet.

However, keep in mind that my wife likes blue. Also, do not worry at this time about acquiring the resources to build the house itself. Your first priority is to develop detailed plans and specifications. Once I approve these plans, however, I would expect the house to be under roof within 48 hours.

While you are designing this house specifically for me, keep in mind that sooner or later I will have to sell it to someone else. It therefore should appeal to a wide variety of potential buyers. Please make sure before you finalize the plans that there is a consensus of the population in my area that they like the features in this house.

I advise you to run up and look at my neighbor’s house he constructed last year. We like it a great deal. It has many features that we would also like in our new home, particularly the 75-foot swimming pool. With careful engineering, I believe that you can design this into our new house without impacting the final cost.

Please prepare a complete set of blueprints. It is not necessary at this time to do the real design, since they will be used only for construction bids. Be advised, however, that you will be held accountable for any increase of construction costs as a result of later design changes.

You must be thrilled to work on such an interesting project as this! To be able to use the latest techniques and materials and to be given such freedom in your designs is something that can’t happen very often. Contact me as soon as possible with your complete ideas and plans.

PS: My wife has just told me that she disagrees with many of the instructions I’ve given you in this letter. As architect, it is your responsibility to resolve these differences. I have tried in the past and have been unable to accomplish this. If you can’t handle this responsibility, I will have to find another architect.

PPS: Perhaps what I need is not a house at all, but a travel trailer. Please advise me as soon as possible if this is the case.

Adapted from



Giving application developers access to the set of broadly reusable REST controllers and resources produced through our aforementioned best practices, requires revisiting aspects of discoverability and consumable production. Simply, unless your services are uncomplicated like the ubiquitous weather example, a WADL is not enough. Moreover, syntactic definition does not equate to semantic understanding. Potential consumers need ready access to supporting artifacts (e.g., usage guide, sample client code) to make resources consumable.

A resource should be discoverable. Wrapping a resource with metadata allows the user to search for other practical resources using varying techniques, and user interfaces. Additionally, IT organizations efficiently deliver resources to potential consumers when well-designed. Minimally, support for mobile, browsers, and deep IDE integration enable users with varying roles to discover the right resources. For example, a business architect may comfortably use domain terminology searches within a browser. However, a designer or developer may prefer a visual search mechanism within a preferred IDE.

Booker Showers


Page 3 of 512345