NetKernel News Volume 7 Issue 1

January 15th 2016

• Repository Updates
• Update: RESTOverlay
• New: SliNKi 5th Generation Wiki Slides
• HTML5: Where are we now?

Repository Updates

Today's update to http-server delivers some extensive updates to the RESTOverlay. Notably: commission-time consistency checks of the REST endpoints and extensive new coverage for HTTP OPTIONS and PATCH methods.

The RESTOverlay wraps an address space and creates a logical external REST API based upon the declared metadata it discovers on the wrapped internal endpoints. (If you're not sure what the RESTOverlay is all about, please take a look at the original release announcement for examples and discussion).

The fundamental problem that the RESTOverlay addresses is to solve the fact that HTTP is "non-normalized". In so much as, in order to determine the correct representation for a resource that is requested it is necessary to consider all of these factors: the URL, the method/verb, the Headers and, if an entity bearing method, the submitted Content-Type.

In essence any public REST API is a multiplexed channel. The job of the RESTOverlay is to be a demultiplexer that routes the external HTTP request to the best normalized ROC resource (internal endpoint) based on an evaluation of the factors listed above.

The RESTOverlay creates a dynamic external REST API that is the merged down set of all potential demuxed internal resources to a set of external endpoints where there is just one endpoint per unique grammar (resource identifier / URL).

The merged set of external REST endpoints are determined during the commission phase of the RESTOverlay. With today's update we have added a new validation stage that performs a formal analysis of the internal and external endpoints and warns if:

1. The internal endpoint does not have a normalized unique grammar
2. The external logical endpoint is potentially routable to two endpoints without sufficient metadata to make a routing decision
3. The grammar of the external endpoint might accidentally overlap with the grammar of another endpoint and (2)

What this means is that there is now a lot more checking to ensure that the endpoints being managed through RESTOverlay are well formed and that demuxing will be consistent. This means that at development time you should get much more realtime information if your endpoints are not consistent.

Here's an example of the type of warning that you may now see if you have two grammars that potentially overlap...

W 12:20:19 RESTOverlay   Ambiguous External Grammar endpoint [ep:ISUR3U-56ZBD6] has potentially
ambiguous simple grammar [pub/{compressible}] overlapping [pub/{incompressible:.*\.(jpg|png)}  ]
and all demux fields are degenerate

Here we see there are two endpoints one with a grammar

pub/{compressible}

and another with

pub/{incompressible:.*\.(jpg|png)}

While these are different, its clear that first overlaps with the second and so you need to be aware in case this was an oversight.

The last part of the warning: "all demux fields are degenerate" - is saying there is not enough additional distinct REST metadata to make a demultiplex decision. (Degeneracy in quantum mechanics means that all particles in a system have the same states - which is exactly what is happening here - all potential resource states are equivalent unless you add a differentiating metadata state - the ROC system is degenerate).

Sometimes you want your grammars to overlap, in which case you can take over and prevent the warning by adding a

<ignoreAmbiguityWarning/>

tag to your endpoint's <rest> metadata section.

Prompted by some great suggestions from our chief REST correspondent, Brian Sletten, we also introduced the following features...

405

If the requested method is not supported you now see a 405 response with an Allow header showing the valid methods for the resource eg...

response
---------
HTTP/1.1 405
Allow: GET, PUT, POST

OPTIONS

The RESTOverlay now automatically handles OPTIONS requests. For example...

request
---------
OPTIONS /example/buddies.xml HTTP/1.1
Host: www.example.com

response
---------
HTTP/1.1 200 OK
Allow: GET, PUT, POST, OPTIONS, HEAD, DELETE, PATCH
Accept-Patch: application/example, text/example

Notice that if a PATCH method exists the OPTIONS returns an Accept-Patch header with patchable content types.

PATCH

If you submit a PATCH for a resource and you also now provide the Etag of the last state of the resource as an If-Match header, then the RESTOverlay will first verify that the GET of that resource has the same Etag hash before allowing the PATCH to be submitted. For example...

PATCH /file.txt HTTP/1.1
Host: www.example.com
Content-Type: application/example
If-Match: "e0023aa4e"
Content-Length: 100

If the target patch resource does not match the If-Match then the following error response is given...

Conflicting modification:  When a client uses either the If-Match or
If-Unmodified-Since header to define a precondition, and that
precondition failed, then the 412 (Precondition Failed) error is
most helpful to the client.  However, that response makes no sense
if there was no precondition on the request.  In cases when the
server detects a possible conflicting modification and no
precondition was defined in the request, the server can return a
409 (Conflict) response.

If it does match but there is no endpoint that can accept the PATCH content-type then this error response is given...

 Unsupported patch document:  Can be specified using a 415
 (Unsupported Media Type) response when the client sends a patch
 document format that the server does not support for the resource
 identified by the Request-URI.  Such a response SHOULD include an
 Accept-Patch response header as described in Section 3.1 to notify the
 client what patch document media types are supported.

Its that time of year when you know spring is around the corner and, with the seasonal regularity of the emergence of the first snowdrop, we have released a brand new version of the SliNKi HTML5 presentation application.

If you didn't know about SliNKi its actually shipped with NetKernel as part of the wiki documentation system. Its an HTML5 slide application that allows you to write slides using wiki markup. Because it exploits ROC resource composition it is extensible with arbitrary macros implemented as ROC micro-services.

To get the new version just accept today's Apposite update.

If you already knew about SliNKi then this is what's new...

1. Full responsive design - slides scale to fit any screen size!
2. Overview mode to see thumbnail view of all slides. Allows for random access - no more embarrassing presenter moments paging back and forward to find the right slide.
3. Canvas mode - allows you to draw on slides to make presenter points
4. Print mode - special view to ensure clean two-up printing.

Its a very big step forward. But I'll let it show you itself, click the image...

Now use left/right arrow keys to page slides, or click in the left/right border.

Try the following keys:

• o - toggle overview mode - to see thumbnails (or right click)
• p - toggle print mode
• c - toggle canvas drawing mode (right click now shows palette tools)
• e - erase canvas

Try resizing the window to see responsive slide scaling.

Legacy presentations will carry on working. To use the new version just change your old {slinki} declaration to {slinkiBespoke}

Finally there's one more new feature we'll be making available soon. The slide engine now supports a classroom mode in which any browser viewing the same slides as the presenter will get page transition events - so the whole class stays in sync. In effect there is now no need to have a projector to do presentations!

The classroom system is zero configuration - all the presenter has to do is tell the class the URL of the slides with the full hostname/ip address and not a localhost URL.

I'm really looking forward to my next public talk at the London MUGL on the 27th.

In the days before SliNKi, Bob Dylan had to improvise.

HTML5: Where are we now?

So Microsoft has almost finished throwing IE under the bus. About time. As predicted, we're finally in the age of UUIAACRNRLOHTTP...

See my newsletter article "HTML5 Something is happening" from 2010!