developer adoption

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 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.