| Verb | /expressions | /expressions/"k" |
| GET | return a list of expression identifiers even if empty. Return a 200 success code | return the full details of expression "k". If "k" doesn't exist then return a 404 error |
| POST | add the requested object if the supplied key in the object doesn't exist. Return a 201 success code as well as the key "k", otherwise return a 400 error. | not allowed, return a 400 error |
| PUT | not allowed, return a 400 error | modify the database with the given object if the supplied key both exists in the database and matches the key in the supplied object - return a 200 success code. In all other circumstances return a 400 error. |
| DELETE | not allowed, return a 400 error | delete the database entry with the given key if it exists in the database and return a 200 success code. In all other circumstances return a 400 error. |
Let's go through each of the cases above in turn with minimal discussion of the code. I'm also going to tidy up the code a little, correcting the HTTP responses, making sure we're calling the correct messageSuccess and messageError functions accordingly.
For the case where we deal with urls of the form http://xxx/expressions, ie: without any key we make the matching in the second case statement in the start function:
function start(url){
match (url) {
case {path: [] ... }: hello();
case {path: ["expressions" ] ... } : expressionsRESTendpoint();
case {path: ["expressions" | [ key | _ ] ] ...} : expressionWithKeyRESTendpoint(key);
case {~path ...}: error();
}
}
which detects URLs without a key associated and passes these off to the expressionsRESTendpoint function:
function expressionsRESTendpoint(){
match(HttpRequest.get_method()) {
case{some: method}:
match(method) {
case{get}:
expressionsGet();
case{post}:
expressionsPost();
case{put}:
messageError("PUT method not allowed without a key",{bad_request});
case{delete}:
messageError("DELETE method not allowed without a key",{bad_request});
default:
messageError("Given REST Method not allowed with expressions",{bad_request}); }
default:
messageError("Error in the HTTP request",{bad_request});
}
}
which matches the GET and POST verbs, and then anything else with an HTTP 400 Bad Request, plus a natural language error message.
Because network programming suffers from the leaky abstraction problem we also need to catch the cases where we fail to get a method, in this case the default: of the outer match block handles this.
The functions expressionsPost and expressionsGet are as described earlier in part 3.
The case where a key is supplied with the URL, this is handled by the 3rd case statement in the start function and control is passed to the expressionWithKeyRESTendpoint function , which operates in the same way as the "without key" case:
function expressionWithKeyRESTendpoint(key){
match(HttpRequest.get_method()) {
case{some: method}:
match(method) {
case{get}:
expressionGetWithKey(key);
case{post}:
messageError("POST method not allowed with a key",{bad_request});
case{put}:
expressionPutWithKey(key);
case{delete}:
expressionDeleteWithKey(key);
default:
messageError("Given REST Method not allowed with expressions with keys",{bad_request});
}
default:
messageError("Error in the HTTP request",{bad_request});
}
}
The procedure to GET is relatively straight forward in that we check that a record with the given key exists and match the result accordingly:
function expressionGetWithKey(key){
match(?/regexDB/expressions[key]) {
case {none}:
messageError("No entry for with id {key} exists",{bad_request});
case {some: r}:
Resource.raw_response(
OpaSerialize.serialize(r),
"application/json",
{success}
);
}
}
Deletion is also relatively straightforward:
function expressionDeleteWithKey(key){
match(?/regexDB/expressions[key]) {
case {none}:
messageError("No entry for with id {key} exists",{bad_request});
case {some: r}:
Db.remove(@/regexDB/expressions[key]);
messageSuccess("{key} removed",{success});
}
}
The expression: ?/regexDB/expressions[key]
is used to check existence, returning an option type which we handle
To remove a record from a database we use the function Db.remove which takes the record as a parameter. Note the use of the @ operator which returns the a reference path to record in the database. Opa's database functions are fairly comprehensive and are better explained in Opa's own documentation - specifically in this case section 14.7.
Now we get to the PUT case; to understand this properly we need to break this down:
- First we check if the request contains a body.
- If successful, we check that the supplied key exists
- If successful, we deserialise the body, which should be JSON
- If successful, we convert this to an Opa record and match it to the type regexExpression.
- If the key supplied in this object (exprID field) matches the key used in the URL then we simply replace the record in the database in the same manner as we make with our earlier POST function.
function expressionPutWithKey(key){
match(HttpRequest.get_body()) {
case {some: body}:
match(?/regexDB/expressions[key]) {
case {none}:
messageError("No entry for with id {key} exists",{success});
case {some: k}:
match(Json.deserialize(body)) {
case{some: jsonobject}:
match(OpaSerialize.Json.unserialize_unsorted(jsonobject))
case{some: regexExpression e}:
if (e.exprID == key) {
/regexDB/expressions[e.exprID] <- e;
messageSuccess("Expression with key {e.exprID} modified",{success});
}
else {
messageError("Attempt to update failed",{bad_request});
}
default:
messageError("Missing or malformed fields",{bad_request});
}
default:
messageError("No valid JSON in body of PUT",{bad_request});
}
}
default:
messageError("No body in PUT",{bad_request});
}
...and with that we conclude the initial development of the application or service (depending on your point of view) and shown basic database interaction, simple processing of URLs, handling of JSON serialisation/deserialisation and handling of the major HTTP methods: GET, POST, PUT and DELETE, plus some simple error handling.
The code up to this point is available on SourceForge and the file you're looking for id tutorial4.opa.
Now for a little discussion...is this the best we can do and why Opa? To answer the second question first, Opa gives us a level of abstraction in that we've not had to worry about many aspects of programming internet based services that many other frameworks have. In a later part we'll talk more about how Opa decides to distribute code between the client and server plus how to use Opa's features for distributing code for scalability and fault-tolerance. So Opa is making a number of architectural decisions for us, in part this is embedded in the nature of Opa - being a compiled language not an interpreted language. Furthermore Opa is strongly typed which means all of our typing errors (well most) are already caught at compile time. This simplifies debugging and forces a more disciplined approach to programming; there is however a caveat (or two) to this last statement.
The code written here is fully functional, written in an agile manner (which may or may not be a good thing) and also written in a rigorous manner (refinement of specification, testing etc). What is wrong with the code is that it is profoundly ugly and that comes from the style of development which in this case has been based around developing a set of individual use cases (eight of them, 2 families of access and 4 verbs).
While use case based development provides us with a good deal of the information we need to know about how our system needs to behave and in what cases, and indeed the individual use cases compose quite nicely - our program works doesn't it? - this does not result in an elegant, maintainable piece of software that performs nor satisfies our needs well. For example, if we need to change how we access the database, or even reuse functionality we end up reintroducing similar code again and often trying to find every instance of code that performs that functionality and modifying that consistently. For example, look how many times we've needed to check whether deserialisation needs to be performed and checked for, or that notice how the patterns for each of the two major use case families (with keys and without keys) are broadly similar but we have repeated code.
What we're left with here is building to be a massive amount of technical debt - once we've added code to manage sets of expressions this becomes painfully obvious; I'm not going to do that in this series, I want (need!) to rewrite this better now. Read the interviews with Ward Cunningham and Martin Fowler about this and you'll see why the code here isn't that elegant. In the next parts of this series I'll refactor the code, take more advantage of Opa's functional nature and show how architecting our design properly, worrying about separation of concerns produces more maintainable code with much higher levels of reuse.
1 comment:
Thanks Ian, you've encouraged me to get my feet wet with Opa.
Looking forward to Part 5!
Post a Comment