REST

Corporate Culture

Influencing REST Behavior and Relationships

To determine and shape organizational behavior that sustains REST efforts over time is often the work of change management specialists. However, conceptualizing the role of REST is easier if we examine the intersection of major influences, such as organizational and individual characteristics. Some influences include:

  • Corporate culture
  • Major decision-making processes
  • Budgeting processes
  • Incentives and penalty structures
  • Compensation linkages to corporate goals and mantras
  • Portfolio management processes
  • Architecture process (definition, acquisition, implementation)
  • Architecture practice (solutions development)
  • Corporate performance metrics⎯return on invested capital (ROIC), revenue and market share growth, cost controls
  • Promotion and advancement criteria

Key factors in the context of REST determine how effective process changes are within an organization. Understanding key process relationships helps a governance board design better REST resources.

For example, the relationship of the budgeting office to project execution helps align budget oversight with the project. Without proper budget-to-project alignment, teams might build project-centric resources. Unfortunately, project-centric resources do not fit the broader needs of an organization. Another example, the relationship between the procurement office and enterprise architecture. Does the acquisition process reflect the goals and standards of the Enterprise Architecture (EA) organization? If not, how can the acquisition process change to better reflect goals and standards?

Another critical relationship is between EA and project or solution architecture, which connects architecture through governance to downstream activities. If there is a disconnect between enterprise architecture and architecture designed at the project level, the result may produce disjointed architecture.

The internal relationships reflect how organizational culture and stakeholder influence converge to either facilitate or hinder REST implementations. There are no easy answers. However, the development of complementary and supportive relationships increase the possibility of successful REST initiatives.

REST Governance Separation of Concern

REST initiatives, in conjunction with other architectural approaches, force IT organizations to recognize teams producing resources are not likely to be the consumers of those resources. Unlike traditional application development, REST is built upon the premise that a set of resources can be used within a wide range of applications. REST depends on production and consumption separation.  The distribution vehicle must allow resource producers to communicate with resource consumers. Observing and consulting for many REST implementations, we have defined the production, distribution, and consumption concerns:

Production: Identification of and governance over the development and maintenance of existing and newly defined candidate reusable resources

Distribution: Publication of those resources for widespread dissemination to potential resources consumers

Consumption: Discovery of and governance over the appropriate use of resources within application development projects

Executing responsibilities within governance concerns through manually defined and managed procedures is technically feasible. However, essentials for IT organizations of any size to build a successful REST implementation include solving political and organizational issues. In addition, selecting appropriate tools such as a resource, repository/registry to automate governance and distribution resources also help build successful REST implementation.

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.

http://wp.me/p2MYVz-k

Booker Showers

29 Tips: Build Appealing REST Resources for Fun and Profit

 

A clear design philosophy can make REST implementation Fun and Profitable. Unfortunately, a company attempting to implement REST without guidelines will waste vast sums of money.

Thinking about implementing REST services? The following tips will help you plan a successful REST implementation:

  1. Consider REST if data returned is not dynamically generated and can be cached
  2. Use REST when bandwidth is particularly important and limited
  3. Use REST for lightweight resource elements within an organization only for integration purposes.
  4. Consider REST for web delivery or aggregation into existing websites because services can be exposed with XML and JSON. HTML pages can consume these resources without significantly refactoring an existing website architecture.
  5. Consider REST when exposing components across a firewall and to control clients who access the resource.
  6. Consider REST when supporting AJAX based clients.
  7. A REST resource should be completely stateless.
  8. A concrete implementation of a REST resource MUST follow four basic design principles:
    • Use HTTP methods explicitly
    • Be stateless
    • Expose directory structure-like URIs
    • Transfer XML, JavaScript Object Notation (JSON), or both.
  9. When creating a resource in a REST network (i.e., the Web) conceptualize and identify entities that need to be exposed as resources.  Look at the entire system and see what nouns (data) can be identified.
  10. Create a URI to each resource and ensure the resource is a noun, not a verb.
  11. Categorize resources in REST according to if a client can receive a representation of the resource, or if a client can modify (add to) the resource.
  12. Response formats should be specified using a schema.
  13. REST URIs should be nouns and easy to recognize.
  14. Hide server-side scripting technology file extensions (.jsp, .php, .asp), to allow porting to something else without changing the URIs.
  15. Keep everything lowercase.
  16. Substitute spaces with hyphens or underscores (one or the other).
  17. Avoid query strings as much as possible.
  18. Use a “/” in the URI to express parent-child relationships.
  19. REST URIs should be static in nature so that when the resource changes or the implementation of the service changes, the link stays the same to allow bookmarking.
  20. Users of REST resources should not derive metadata from the URI.
  21. Response payloads in REST should be simple, human readable and connected.
  22. Give client applications the ability to request a specific content type best suited for the client application.
  23. All resources transferred over REST must be marked cacheable, or non-cacheable (at minimum).
  24. REST deployments should be layered.
  25. Use a resource based approach for mobile devices.
  26. Use HTTP error codes along with suitable additional information in a header like X-Application-Error-Code: for differentiating multiple mappings to the same code used for REST exception.
  27. Do not return empty XML documents in case of error.
  28. Always return a response document.
  29. All REST responses should return a request ID like for troubleshooting purposes.

http://wp.me/p2MYVz-1c

Booker Showers

REST Governance Key Signature

The REST Governance Key Signature

 

Much of the hype around service governance is focused on operational governance. Defining, tracking, and managing factors like service-level agreements (e.g., average response time, peak response time, average throughput, peak throughput) and authorization policies (e.g., users from organization A are allowed to invoke this service while users from organization B are not) are very important.  Once service components are up and running within an organization’s IT infrastructure governance is necessary.

Operational governance and management are necessary but insufficient for successful service deployment. To effectively define and implement a REST service, and not simply implement a series of point-to-point REST services masquerading as REST, which create another layer of technology spaghetti, REST services must extend governance back to development and architectural REST perspectives. Find a way to seamlessly bind REST perspectives to enable effective information flow in multiple directions⎯from architecture to development to operations.

Taliferro thoroughly investigated each governance perspective.

Architectural Governance

Architectural governance at the enterprise architecture (EA) level involves three key elements:

  1. core decisions about business or technological functionality within the enterprise
  2. documenting decisions so that downstream consumers (the teams responsible for developing and deploying services and    applications) can quickly understand and make effective use of those decisions
  3. reviewing project-specific application of decisions

In order for an EA team to execute tasks, the team must have an effective way to disseminate produced knowledge assets. In addition, the team must track and understand which knowledge assets are applied to specific projects. Further, an EA Team needs to document the review of project-specific decisions.

Design-Time Governance

In many ways, Software Development Life Cycle (SDLC) governance within a REST initiative is a reflection of decisions made at the enterprise architecture (EA) level. Decisions about the scope and granularity of implemented business services and technical approach used in implementing the services must be applied to specific service production or consumption (i.e., application development) projects.

However, SDLC governance extends beyond appropriate application of EA guidance to the analysis, design, implementation, and testing of the resulting services and/or applications required by the IT project. Regarding service production, SDLC governance involves the progressive “hardening” of a service. Services progress through requirements definition, design, implementation/unit test, and integration/system test phases to eventual deployment in the operational environment, oversight is needed.

When applied to service consumption, governance may involve both internal project-specific reviews (e.g., appropriate services selected, requirements for new services identified). External reviews from the perspective of service providers allow for such questions as:

Does the use of this service within this application conform to enterprise-specific or government-mandated privacy rules?

Does the service implementation contain open source components?  If so, do the components compromise enterprise-specific intellectual property?

Operational Governance

Operational governance/management within REST involves applying appropriate business and technical policies (e.g., groups and users allowed to invoke a particular service, minimum throughput and response time expectations required of a service) to deployed services. Business policies are often implemented within REST by a Service Bus or some fabric integrated with the enterprise’s authentication and authorization infrastructure, while technical policies are typically monitored by a services management platform. The cumulative set of governed technical policies is often referred to as a service-level agreement (SLA).

Examples of SLA-level technical governance elements within REST:

  • Average throughput
  • Peak throughput
  • Type and description of committed SLA
  • Availability
  • Consuming service clients
  • Hardware and software configuration
  • Fault history
  • Alert thresholds

Political Aspects of REST Governance

How do we map  governance disciplines into an organization’s structure and roles? The nature of REST governance creates a new discipline with implications for existing corporate and IT institutions. The implications affect new organizational structures and processes and the politics associated with those structures and processes.

To make governance a valuable and necessary function that supports REST migration one needs to understand

  • corporate service policies
  • what governance means
  • how governance helps achieve successful implementation
  • the impact on current IT governance processes.

Some processes include budgeting and project approval, portfolio management activities, and ongoing oversight of projects to assure budgetary compliance. Applying governance to REST activities is critical because changes to normal IT governance processes for budgeting and portfolio management may be necessary.

Think about the budgeting process of an organization. The budgeting process has tremendous impact on organizational behavior in general, and IT departments in particular. Without budgetary project control to influence REST adoption and reusable services as fundamental design concepts, projects are only driven by requirements of a specific business unit, or project. The same logic applies to portfolio management.  Governance, budgeting, and portfolio management are methods used to influence business unit behavior, and IT departments to aggressively support REST and reuse. Enterprise architecture processes undergo changes as a result of an organization’s REST initiative. Often the architecture process and organization have to be restructured to accommodate REST requirements because the skills, roles, and functions of an EA team are not appropriate for a REST initiative.

Examine the process of architecture as tiers of activities: one tier involves architecture strategy and goals, definition of elements, standards, and the other architectural goals. The latter tier involves funded projects either through architecture, acquisition or implementation. Even though management may want both tiers to interdependently function, the two tiers are related, yet distinct processes. For example, at corporate headquarters a chief architect or central architecture group along with solution architects are assigned to projects. They build systems and implement technologies and standards. Usually, the business unit that funds a project has the most influence. The behavior associated with enterprise architecture is similarly related to the organization and processes used to achieve the goals of REST:

  • architecture compliance
  • portfolio management
  • budgetary compliance.

 

Summary

Don’t think managing your REST implementation operationally is enough. Keeping tabs on execution does not ensure the service is really supporting overall business goals. Traceability to business goals/priorities through EA to SDLC to operations make REST implementation successful in the enterprise. Equally important, do not minimize organizational influences that are needed – monolithic, project-centric funding models are not likely to work in the world of REST.

http://wp.me/p2MYVz-P

Booker Showers

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., music.taliferro.com/artists/calima-shatiday/).  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.

http://wp.me/p2MYVz-1a

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

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.

http://wp.me/p2MYVz-18

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

REST Will Soon Fade into Oblivion

REST Will Soon Fade into Oblivion

Like other promising technologies I can confidently state that REST will soon head to the technological graveyard. Why? The use of REST seems to be based on opinions instead of rules. I don’t understand how REST turned into such a mishmash of divergent technologies when there is actually a well documented thesis written on the subject. We are in an era where loose interpretation of REST causes confusion for companies trying to implement the architectural style.

The REST technology leaders are dictating the market direction of REST on faulty material or hearsay. If only I had a nickel for every time I have been told that my arguments on proper REST architecture are academic, I would be rich. When people mention the term REST API, I automatically know they have no clue about REST. The sad part is that this term is repeated on site after site, blog after blog. Representational State Transfer Application Programing Interface? Seriously? This ill-conceived grouping of acronyms I predict will bury REST.

An architectural style originally developed for exploiting the Internet for data access turned into a mechanism that creates functional interfaces is a sure sign that REST is headed towards extinction, which usually happens when there is a complete misunderstanding of an architecture’s intent. Unfortunately, REST is now used as another buzz acronym and to pad resumes.

However, REST is simply an architectural style developed to transfer data in a usable fashion utilizing HTTP. The evidence of REST implementation lies in the verbs used, and its usage similarity to the database domain. Create, Retrieve, Update, and Delete in the database domain. POST, GET, PUT, and DELETE in the HTTP domain.

How much more evidence is needed to convey that REST is for data, and not for interfaces and function calls? Nevertheless, market leaders are force fitting REST as the new SOAP. I surmise this is because most of the architects are former SOAP architects. The SOAP architects are using analogies they are most familiar with – SOAP.

SOAP is not REST. SOAP is functional. REST is data. Regrettably, we will never see implementations that reflect the academic argument because the market drivers have already dictated that REST is the new SOAP. Consequently, REST extinction in 5 years or fewer is indeed possible; unless the IT industry reevaluates its understanding of Roy Fielding’s academic thesis as intended in real-world applications.

http://wp.me/p2MYVz-qI

Booker Showers

Distribution

Distribution

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.

http://wp.me/p2MYVz-mx

Booker Showers

 

Page 1 of 212