api

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

Check Point

Recommended Service SDLC Governance Checkpoints

Check PointAfter defining our first set of services we need to build and deliver. Developing services in REST (i.e., for purposes of reuse across multiple applications) usually requires more of the production team than a single-use component, module, or object. For example, a reusable service is maintainable, discoverable, and consumable.

Maintainability introduces such concepts as version control, models, and other design documentation. In addition, maintainability involves requirements traceability (why was the asset implemented in a certain way from a technical and business perspective).

Discoverability forces us to consider how we help potential consumers of the asset find the asset.

Consumability involves looking at the asset from a downstream project planning point of view to determine how to use the asset. For instance, is there a user guide, a well-documented API, sample code, and other artifacts available to help a user rapidly understand how to apply the asset? Further, are dependencies on other assets (and to prior versions of the asset) specified and easily navigated?

We achieve high standards for our services under development by establishing standardized governance/review checkpoints throughout the service SDLC. Taliferro IT Consulting recommends at a minimum, organizations should review services under development upon reaching the following points in the SDLC:

  • Requirements Complete: All business requirements documented and initial service definition specified (ideally as WADL) to allow reviewers to validate the service against its business architectural context
  • Design Complete: Implementation approach defined with sufficient documentation (e.g., design models, relevant legacy APIs identified) to allow reviewers to validate design against technical, application and/or integration architectural contexts
  • Implementation Complete: Service implemented and deployed in a test environment with sufficient supporting documentation (e.g., sample code, test cases and results, usage guide) to enable a potential consumer to understand the service and to trust its quality and stability

Other review points are necessary based on organizational needs and objectives. However, refrain from overwhelming your development teams with process for the sake of process. Otherwise, you will quickly instill a revolt of the masses by forcing seemingly arbitrary hoops for developers to jump through in the process of completing their work.

Management’s objective should be to instill “just enough process” – not an unnecessary workload. Provide enough guidance at key points in the production and consumption life cycles to make sure things stay on track. Using the approach described, you will very likely reach the right level of process for your organization.

Begin with as lightweight a process as you think will work, and then add process steps as needed. Ultimately, a well-designed services registry/repository can assist in automating governance processes. The result is a reduction in “organizational friction” that often hinders all involved from “doing the right thing.”

How To Expose Internal Systems As REST

How To Expose Internal Systems As REST

To expose internal systems as REST, you must first understand the value of resources and controllers. Once resources and controllers are understood, thinking in the abstract is next. Abstract thinking (thinking about the parts instead of the whole) create value for the developers you are trying to attract.

Consider as an example a Bird and a Dinosaur.  Each creature has attributes and behaviors that make them distinct. They also have shared attributes (such as seeing and walking). Let’s say for illustrative purposes that Bird and Dinosaur are finished products (in the same way internal systems are finished products).

In the diagram below, Bird and Dinosaur have been deconstructed (as a simple example). This deconstruction allows us to create new unique animals and apply behaviors, such as walking and flying, to the unique animal.

Animal Deconstruction

 

To monetize internal systems, you must think similarly about abstract deconstruction. Deconstruction produces a framework that allows developers to create unique applications. However, one must not confuse REST and API as the same. REST is an architectural style that uses the HTTP URL to access information. URLs can be consumed by APIs or accessed as RAW URLs. Let’s not lose sight of what REST stands for; Representational State Transfer, which means transferring the state and make-up of data via a URL.  REST’s ideal purpose is for data.

Now let’s look at a more concrete example. If a 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. Instead of looking at the enterprise as a whole, try to look at each individual platform’s characteristics and behaviors in the abstract as shown in the diagram below.

Deconstruction Example

From the abbreviated diagram above, as a developer, I can now begin to imagine mixing and matching the various attributes and behaviors into some type of software product, or incorporating attributes and behaviors into my own product. To focus on parts instead of predetermined functionality 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. After you have deconstructed  the internal systems, you then want to create unique offers (or products) to show developers how they too can use the framework to create their own products. In the diagram below, a telecommunication company could leverage Voice, Media and the SMSC to create a framework and possibly allow developers to create something totally new. Leveraging and monetizing internal systems can be done with the right mindset.

REST as Template Services

Template ServicesCompany management consistently struggle with exposing internal products as REST services. There is a lack of balance between organizing internal products to be used in combination with other internal products (to create a new type of service) and REST principles.  Understanding the difference between controllers and REST resources will eliminate confusion and misuse of fundamental REST principles.

Previously explained, REST is best used for static objects that Create, Retrieve, Update, and Delete  (i.e., the HTTP equivalent POST, GET, PUT, and DELETE). If the service acts as a function, consider designing the service as a REST controller (see How to identify objects as REST Controllers or Resources). Otherwise, the service is data.

The ultimate REST architecture is a service structure that combines with other REST services to create a totally new service as depicted in the following diagram:

A Powerful REST Architecture that Focuses on Monetization

REST Template Services

The platform is the application, or system exposed to external developers. Platforms are used individually or with other Platforms to create unique services.

The service template defines configurable attributes of a platform. The service template is used to create a service, which has commercial value to an enterprise or an independent developer.

The service variant is a configured version of a service template.  The service variant is an item with the necessary configuration to provide value to a developer and supports necessary provisioning actions.

An offer is a bundle of services exposed via an API, which consist of one or more service variants, offered to developers for consumption to create applications.

In summary, when creating a REST architecture remember one internal service can be used with another to create a completely new API.  Try to stay abstract. Do not release a finished product as a REST service by pointing the URL to the product. When a finished product is used as a REST service, a developer has no options to consume the API.  Separate data as resources and actions as controllers.  Nouns vs verbs.