Fluid-Schema-Version HTTP Header

4 min readSep 24, 2018

Imagine deploying your latest web service version to production unencumbered by the payload structures currently in use by the community. The aim the Fluid Manifesto is to promote a set of techniques and approaches that allow exactly that. The Fluid-Schema-Version header is the glue that allows Fluid-Web-Services to work with Fluid-Schema-Evolution to deliver the above.

Getting Going

Let’s revisit the /users endpoint upgrade introduced in the web services article and see how using the Fluid-Schema-Version header avoids the need to have a two stage downgrade process.

The client was developed against schema version 6 (more on discovery in the next section) and includes this with every web service request:

> GET /users/Simon HTTP/1.1
> Fluid-From: Joe
> Fluid-Schema-Version: 6< HTTP/1.1 200 OK
< Content-Type: application/json{
  "name": "Simon",
  "location": "London",
  "hobby": "coding"
}

When a new version of the endpoint is rolled out the JSON structures will have changed resulting in a new schema version. When the web service is called there is a check to see if there have been any changes to the JSON structure associated with the requested endpoint between the requested and current schema-versions. If there has been a change downgrade scripts are automatically applied. Using the Fluid-Schema-Version header we go directly to the downgraded structure without needing to use fallback URLs. We still get the warning about the expiry of the outdated /users endpoint as before.

> GET /users/Simon HTTP/1.1
> Fluid-From: Joe
> Fluid-Schema-Version: 6< HTTP/1.1 200 OK
< Content-Type: application/json
< Fluid-Expiry: 21 Use updated /users structure{
  "name": "Simon",
  "location": "London",
  "hobby": "coding"
}

When the schema-version is updated to the JSON structure associated with that schema version is served.

> GET /users/Simon HTTP/1.1
> Fluid-From: Joe
> Fluid-Schema-Version: 7< HTTP/1.1 200 OK
< Content-Type: application/json{
  "name": "Simon",
  "city": "London",
  "hobbies": [ "coding" ]
}

Discovery

When developing a fluid enabled web service the following endpoints are recommended:

/fluid/latest-schema-version: The latest fluid schema version. This is the version clients would use as their Fluid-Schema-Version when they start using the web service.

/fluid/api[?server=<server>]: The OpenAPI (swagger) definition of the available web services (which in most cases will be what backs the generation of the fluid metadata). If provided the server parameter should be returned in the OpenAPI definition.

/fluid/metadata/<schema-version>: the metadata associated with the given schema version (this contains details of which endpoints have modified JSON structures and the associated migrations scripts) as described in Fluid Schema Evolution.

Fluid HTTP Proxy

As the fluid detection and migration activity is a cross cutting concern it makes sense for this to be done in a dedicated layer. What we describe here is the Fluid HTTP Proxy which uses metadata from the underlying fluid-enabled web service to automatically apply migrations scripts as needed.

The Fluid HTTP Proxy is configured with the URL of the web server that is running the latest version of the services. On a client request to a web service the proxy will pass on the request to the underlying web service. If the requested schema-version is compatible with the requested version the body of the request can be returned un-altered. If JSON downgrade, or upgrade is required all the necessary migration scripts are downloaded from the /fluid/metadata endpoint, and the final body returned to the client will be the JSON structure output from the migration.

Fluid Reporting

Fluid web services allows endpoints to constantly improve. When either providing and consuming fluid web services reporting is needed to give a version compliance summary for each endpoint. The main report for service providers is the Client Use report and the main report for service consumers is the Server Use report described below. The Fluid HTTP proxy generates these reports.

Server Use

This report takes as a parameter the base URL of the services and the number of days to look back (7 by default). It provides a report that shows for each service:

The web service endpoint
A RAG status which will be green if there are no expiring calls
The total number of requests
The number of calls that will reach expiry in 7 days (RAG=red)
The number of calls that will reach expiry in 30 days (RAG=amber)

Clicking on a particular number will give a breakdown of the calls by fluid-from.

Client Use

This report takes as a parameter the fluid-from name and the number of days to look back (7 by default). It provides a report that shows for each

The web service endpoint
A RAG status which will be green if there are no expiring calls
The total number of requests
The number of calls that will reach expiry in 7 days (RAG=red)
The number of calls that will reach expiry in 30 days (RAG=amber)

Conclusion

We’ve seen how the different pieces of the Fluid architecture fit together to form a coherent whole. Following this approach holds the promise that we can develop and deploy web services in an truly agile way.