The making of Restbucks
Even great coffee starts with a very small seed. In this blog post we'll be implementing the worlds best known RESTful coffee shop with IRIS. IRIS is an open source project for create Interaction, Reporting and Information Services; what better example for our project than a nice cup of Restbucks coffee. If you happen to be reading this post with a cuppa, Restbucks will be ready for service by the time you finish.
Entity Relationships
We're going to kick start our example with a simple Entity Relationship diagram and follow most of the steps in the Quickstart. The Restbucks database contains Orders and Payments:
It seems a little odd for a Java project to start an example using Visual Studio, but one of the easiest ways to get an IRIS project started is to create services from an EDMX file. Visual Studio is still the best tool to create our Restbucks EDMX file. With only a few minor alterations to remove unsupported annotations and keeping complex types out of the picture for the moment it looks as follows:
<?xml version="1.0" encoding="utf-8"?>
<edmx:Edmx Version="1.0" xmlns:edmx="http://schemas.microsoft.com/ado/2007/06/edmx" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
<edmx:DataServices m:DataServiceVersion="1.0">
<Schema xmlns="http://schemas.microsoft.com/ado/2006/04/edm" Namespace="RestbucksModel">
<EntityContainer Name="Restbucks" m:IsDefaultEntityContainer="true">
<EntitySet Name="Orders" EntityType="RestbucksModel.Order" />
<EntitySet Name="Payments" EntityType="RestbucksModel.Payment" />
<AssociationSet Name="OrderPayment" Association="RestbucksModel.OrderPayment">
<End Role="Order" EntitySet="Orders" />
<End Role="Payment" EntitySet="Payments" />
</AssociationSet>
</EntityContainer>
<EntityType Name="Order">
<Key>
<PropertyRef Name="Id" />
</Key>
<Property Type="Int32" Name="Id" Nullable="false" />
<Property Type="String" Name="location" Nullable="false" />
<NavigationProperty Name="Payment" Relationship="RestbucksModel.OrderPayment" FromRole="Order" ToRole="Payment" />
<Property Type="String" Name="name" Nullable="false" />
<Property Type="String" Name="milk" Nullable="false" />
<Property Type="Int16" Name="quantity" Nullable="false" />
<Property Type="String" Name="size" Nullable="false" />
</EntityType>
<EntityType Name="Payment">
<Key>
<PropertyRef Name="Id" />
</Key>
<Property Type="Int32" Name="Id" Nullable="false" />
<Property Type="String" Name="authorisationCode" Nullable="false" />
<NavigationProperty Name="Order" Relationship="RestbucksModel.OrderPayment" FromRole="Payment" ToRole="Order" />
</EntityType>
<Association Name="OrderPayment">
<End Type="RestbucksModel.Order" Role="Order" Multiplicity="1" />
<End Type="RestbucksModel.Payment" Role="Payment" Multiplicity="0..1" />
<ReferentialConstraint>
<Principal Role="Order">
<PropertyRef Name="Id"/>
</Principal>
<Dependent Role="Payment">
<PropertyRef Name="Id"/>
</Dependent>
</ReferentialConstraint>
</Association>
</Schema>
</edmx:DataServices>
</edmx:Edmx>
Restbuck Interactions and State Machine
If we take a moment to refer back to Rest In Practice, Section 5.4.1. The Restbucks Domain Application Protocol, we'll see a very useful diagram that describes our client interactions with Restbucks. As the book points out, this diagram is great in terms of understanding the HTTP requests and responses, but to codify the service we need to think in terms of the state machine.
Interactions:
State machine:
If we have to think in terms of a state machine, why do we seldom see services written in terms of a state machine? The Resource Interaction Model (RIM) is a domain specific language to help us do just that. The RIM language is intended to be a conceptual level language that removes the need to understand the HTTP implementation details; at the same time this means we can ensure the RIM implementation is logically correct according to the RESTful constraints - by using verbs, status codes, representations, and links appropriately.
Resource Interaction Model
To turn the generated Restbucks Data Service into an Interaction Service we need to edit the src/main/resources/Restbucks.rim and implement the states from Figure 5-5. Your first task will be to remove the generated CRUD states, and after some small modifications your Restbucks.rim will now look as follows:
RIM visualisation plugin
Restbucks.rim
domain RestbucksModel {
rim Restbucks {
event DELETE {
method: DELETE
}
event GET {
method: GET
}
event POST {
method: POST
}
event PUT {
method: PUT
}
command CreateEntity
command DeleteEntity
command GETEntities
command GETEntity
command GETException
command GETNavProperty
command GETServiceDocument
command NoopGET
command UpdateEntity
initial resource ServiceDocument {
type: item
entity: ServiceDocument
view { GETServiceDocument }
path "/"
GET -> Orders
GET -> Payments
GET -> shop
}
resource shop {
type: item
entity: ServiceDocument
view { NoopGET }
path "/shop"
POST -> OrderCreated
}
resource Orders {
type: collection
entity: Order
view { GETEntities }
path "/Orders()"
POST -> OrderCreated
GET *-> order id=Id
GET title="Payment" *-> payment
PUT *-> OrderUpdated
DELETE *-> OrderCancelled
}
resource order {
type: item
entity: Order
view { GETEntity }
path "/Orders({Id})"
GET title="Payment" -> payment
// Can only update or delete if we haven't paid
PUT -> OrderUpdated (NOT_FOUND(payment))
DELETE -> OrderCancelled (NOT_FOUND(payment))
POST -> PaymentAccepted (NOT_FOUND(payment))
}
resource OrderCancelled {
type: item
entity: Order
actions { DeleteEntity }
relations { "http://relations.restbucks.com/cancel" }
path "/Orders({Id})"
}
resource OrderUpdated {
type: item
entity: Order
actions { UpdateEntity }
relations { "http://relations.restbucks.com/update" }
path "/Orders({Id})"
}
resource OrderCreated {
type: item
entity: Order
actions { CreateEntity }
path "/Orders()"
GET --> order (OK(order))
}
resource Payments {
type: collection
entity: Payment
view { GETEntities }
path "/Payments()"
GET *-> payment
GET title="Order" *-> order
}
resource payment {
type: item
entity: Payment
view { GETEntity }
path "/Payments({Id})"
GET title="Order" -> order
}
resource PaymentAccepted {
type: item
entity: Payment
actions { CreateEntity }
relations { "http://relations.restbucks.com/payment" }
path "/Payments()"
GET --> payment (OK(payment))
}
}
}
Ready for service
Our shop is now ready for business. Let's start our server and POST an order. Using Postman POST the following entry, with Content-Type application/atom+xml to http://localhost:8080/responder/interaction-hateoas-restbucks.svc/Orders()
<?xml version='1.0' encoding='utf-8'?>
<entry
xmlns="http://www.w3.org/2005/Atom"
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xml:base="http://localhost:8080/responder/interaction-hateoas-restbucks.svc/">
<id>http://localhost:8080/responder/interaction-hateoas-restbucks.svc/Orders(1)</id>
<title type="text" />
<updated>2013-10-28T11:57:15Z</updated>
<author>
<name />
</author>
<category term="RestbucksModel.Order" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
<content type="application/xml">
<m:properties>
<d:size>abc</d:size>
<d:milk>abc</d:milk>
<d:name>abc</d:name>
<d:location>abc</d:location>
<d:quantity m:type="Edm.Int32">1</d:quantity>
</m:properties>
</content>
</entry>
You will receive the following response 201 Created:
<?xml version='1.0' encoding='utf-8'?>
<entry
xmlns="http://www.w3.org/2005/Atom"
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xml:base="http://localhost:8080/responder/interaction-hateoas-restbucks.svc/">
<id>http://localhost:8080/responder/interaction-hateoas-restbucks.svc/Orders(1001)</id>
<title type="text" />
<updated>2013-10-28T23:36:07Z</updated>
<author>
<name />
</author>
<link rel="self" type="application/atom+xml;type=entry" title="order" href="Orders(1001)" />
<link rel="http://relations.restbucks.com/update" type="application/atom+xml;type=entry" title="OrderUpdated" href="Orders(1001)" />
<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Payment" type="application/atom+xml;type=entry" title="Payment" href="Payments(1001)" />
<link rel="http://relations.restbucks.com/payment" type="application/atom+xml;type=entry" title="PaymentAccepted" href="Payments()" />
<link rel="http://relations.restbucks.com/cancel" type="application/atom+xml;type=entry" title="OrderCancelled" href="Orders(1001)" />
<category term="RestbucksModel.Order" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
<content type="application/xml">
<m:properties>
<d:milk>abc</d:milk>
<d:location>abc</d:location>
<d:name>abc</d:name>
<d:size>abc</d:size>
<d:Id m:type="Edm.Int32">1001</d:Id>
<d:quantity m:type="Edm.Int32">1</d:quantity>
</m:properties>
</content>
</entry>
Notice that you can pay this Order by using the 'payment' link:
<link rel="http://relations.restbucks.com/payment" type="application/atom+xml;type=entry" title="PaymentAccepted" href="Payments()" />
You will also need to update your pom.xml to add the HALProvider dependency:
<!-- Add dependency for our hal provider -->
<dependency>
<groupId>com.temenos.interaction</groupId>
<artifactId>interaction-media-hal</artifactId>
<version>0.4.0-SNAPSHOT</version>
<scope>runtime</scope>
</dependency>
With very little effort you could now use the HAL Browser to understand your API:
I hope you enjoyed your coffee.
Even great coffee starts with a very small seed. In this blog post we'll be implementing the worlds best known RESTful coffee shop with IRIS. IRIS is an open source project for create Interaction, Reporting and Information Services; what better example for our project than a nice cup of Restbucks coffee. If you happen to be reading this post with a cuppa, Restbucks will be ready for service by the time you finish.
Entity Relationships
We're going to kick start our example with a simple Entity Relationship diagram and follow most of the steps in the Quickstart. The Restbucks database contains Orders and Payments:
It seems a little odd for a Java project to start an example using Visual Studio, but one of the easiest ways to get an IRIS project started is to create services from an EDMX file. Visual Studio is still the best tool to create our Restbucks EDMX file. With only a few minor alterations to remove unsupported annotations and keeping complex types out of the picture for the moment it looks as follows:
<?xml version="1.0" encoding="utf-8"?>
<edmx:Edmx Version="1.0" xmlns:edmx="http://schemas.microsoft.com/ado/2007/06/edmx" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
<edmx:DataServices m:DataServiceVersion="1.0">
<Schema xmlns="http://schemas.microsoft.com/ado/2006/04/edm" Namespace="RestbucksModel">
<EntityContainer Name="Restbucks" m:IsDefaultEntityContainer="true">
<EntitySet Name="Orders" EntityType="RestbucksModel.Order" />
<EntitySet Name="Payments" EntityType="RestbucksModel.Payment" />
<AssociationSet Name="OrderPayment" Association="RestbucksModel.OrderPayment">
<End Role="Order" EntitySet="Orders" />
<End Role="Payment" EntitySet="Payments" />
</AssociationSet>
</EntityContainer>
<EntityType Name="Order">
<Key>
<PropertyRef Name="Id" />
</Key>
<Property Type="Int32" Name="Id" Nullable="false" />
<Property Type="String" Name="location" Nullable="false" />
<NavigationProperty Name="Payment" Relationship="RestbucksModel.OrderPayment" FromRole="Order" ToRole="Payment" />
<Property Type="String" Name="name" Nullable="false" />
<Property Type="String" Name="milk" Nullable="false" />
<Property Type="Int16" Name="quantity" Nullable="false" />
<Property Type="String" Name="size" Nullable="false" />
</EntityType>
<EntityType Name="Payment">
<Key>
<PropertyRef Name="Id" />
</Key>
<Property Type="Int32" Name="Id" Nullable="false" />
<Property Type="String" Name="authorisationCode" Nullable="false" />
<NavigationProperty Name="Order" Relationship="RestbucksModel.OrderPayment" FromRole="Payment" ToRole="Order" />
</EntityType>
<Association Name="OrderPayment">
<End Type="RestbucksModel.Order" Role="Order" Multiplicity="1" />
<End Type="RestbucksModel.Payment" Role="Payment" Multiplicity="0..1" />
<ReferentialConstraint>
<Principal Role="Order">
<PropertyRef Name="Id"/>
</Principal>
<Dependent Role="Payment">
<PropertyRef Name="Id"/>
</Dependent>
</ReferentialConstraint>
</Association>
</Schema>
</edmx:DataServices>
</edmx:Edmx>
Generating the project mock responder
We now use the above EDMX to generate a simple mock database and mock responder services.
$ mvn interaction-sdk:gen
Once we've executed the generation step we can immediately try to start our project with 'jetty:run'. Using the EDMX provided here in this post does result in one or two errors initially because we want our service to be called Orders; this is a reserved word in SQL. Therefore we need to make one minor correction to the generated table name.
$ mvn clean package jetty:run
21:38:04.177 [main] DEBUG o.h.tool.hbm2ddl.SchemaExport - create table Order (Id integer not null, location varchar(255), milk varchar(255), name varc
har(255), quantity integer, size varchar(255), primary key (Id))
21:38:04.178 [main] ERROR o.h.tool.hbm2ddl.SchemaExport - Unsuccessful: create table Order (Id integer not null, location varchar(255), milk varchar(2
55), name varchar(255), quantity integer, size varchar(255), primary key (Id))
21:38:04.180 [main] ERROR o.h.tool.hbm2ddl.SchemaExport - Unexpected token: ORDER in statement [create table Order]
21:38:04.180 [main] DEBUG o.h.tool.hbm2ddl.SchemaExport - create table Payment (Id integer not null, authorisationCode varchar(255), primary key (Id))
21:38:04.186 [main] DEBUG o.h.tool.hbm2ddl.SchemaExport - alter table Order add constraint FK48E972EB5B9E338 foreign key (Id) references Payment
21:38:04.186 [main] ERROR o.h.tool.hbm2ddl.SchemaExport - Unsuccessful: alter table Order add constraint FK48E972EB5B9E338 foreign key (Id) references
Payment
21:38:04.187 [main] ERROR o.h.tool.hbm2ddl.SchemaExport - Unexpected token: ORDER in statement [alter table Order]
21:38:04.188 [main] DEBUG o.h.tool.hbm2ddl.SchemaExport - alter table Payment add constraint FK3454C9E659675240 foreign key (Id) references Order
21:38:04.189 [main] ERROR o.h.tool.hbm2ddl.SchemaExport - Unsuccessful: alter table Payment add constraint FK3454C9E659675240 foreign key (Id) referen
ces Order
21:38:04.190 [main] ERROR o.h.tool.hbm2ddl.SchemaExport - Unexpected token: ORDER in statement [alter table Payment add constraint FK3454C9E659675240
foreign key (Id) references Order]
...
Oct 27, 2013 9:38:05 PM com.temenos.interaction.sdk.util.ResponderDBUtils fillDatabase
SEVERE: Failed to insert SQL statements.
java.sql.SQLException: Unexpected token: ORDER in statement [INSERT INTO Order]
at org.hsqldb.jdbc.Util.sqlException(Unknown Source)
at org.hsqldb.jdbc.jdbcStatement.fetchResult(Unknown Source)
at org.hsqldb.jdbc.jdbcStatement.executeUpdate(Unknown Source)
at com.temenos.interaction.sdk.util.ResponderDBUtils.fillDatabase(ResponderDBUtils.java:74)
Modify Order.java
@Entity
@Table(name="rb_order")
public class Order {
Modify responder_insert.sql
INSERT INTO `rb_order`(`Id` , `location` , `name` , `milk` , `quantity` , `size`) VALUES('1' , 'abc' , 'abc' , 'abc' , '1' , 'abc');
Data Service into Interaction Service
By default the interaction SDK creates an OData service when generated from an EDMX. OData is a good example of a Data Service - it has links between entities. However, to become an Interaction Service we need to use these links to guide our client interactions. You can open the IRIS default OData javascript client http://localhost:8080/responder and you should see the following :
If we take a moment to refer back to Rest In Practice, Section 5.4.1. The Restbucks Domain Application Protocol, we'll see a very useful diagram that describes our client interactions with Restbucks. As the book points out, this diagram is great in terms of understanding the HTTP requests and responses, but to codify the service we need to think in terms of the state machine.
Interactions:
State machine:
If we have to think in terms of a state machine, why do we seldom see services written in terms of a state machine? The Resource Interaction Model (RIM) is a domain specific language to help us do just that. The RIM language is intended to be a conceptual level language that removes the need to understand the HTTP implementation details; at the same time this means we can ensure the RIM implementation is logically correct according to the RESTful constraints - by using verbs, status codes, representations, and links appropriately.
Resource Interaction Model
To turn the generated Restbucks Data Service into an Interaction Service we need to edit the src/main/resources/Restbucks.rim and implement the states from Figure 5-5. Your first task will be to remove the generated CRUD states, and after some small modifications your Restbucks.rim will now look as follows:
RIM visualisation plugin
Restbucks.rim
domain RestbucksModel {
rim Restbucks {
event DELETE {
method: DELETE
}
event GET {
method: GET
}
event POST {
method: POST
}
event PUT {
method: PUT
}
command CreateEntity
command DeleteEntity
command GETEntities
command GETEntity
command GETException
command GETNavProperty
command GETServiceDocument
command NoopGET
command UpdateEntity
initial resource ServiceDocument {
type: item
entity: ServiceDocument
view { GETServiceDocument }
path "/"
GET -> Orders
GET -> Payments
GET -> shop
}
resource shop {
type: item
entity: ServiceDocument
view { NoopGET }
path "/shop"
POST -> OrderCreated
}
resource Orders {
type: collection
entity: Order
view { GETEntities }
path "/Orders()"
POST -> OrderCreated
GET *-> order id=Id
GET title="Payment" *-> payment
PUT *-> OrderUpdated
DELETE *-> OrderCancelled
}
resource order {
type: item
entity: Order
view { GETEntity }
path "/Orders({Id})"
GET title="Payment" -> payment
// Can only update or delete if we haven't paid
PUT -> OrderUpdated (NOT_FOUND(payment))
DELETE -> OrderCancelled (NOT_FOUND(payment))
POST -> PaymentAccepted (NOT_FOUND(payment))
}
resource OrderCancelled {
type: item
entity: Order
actions { DeleteEntity }
relations { "http://relations.restbucks.com/cancel" }
path "/Orders({Id})"
}
resource OrderUpdated {
type: item
entity: Order
actions { UpdateEntity }
relations { "http://relations.restbucks.com/update" }
path "/Orders({Id})"
}
resource OrderCreated {
type: item
entity: Order
actions { CreateEntity }
path "/Orders()"
GET --> order (OK(order))
}
resource Payments {
type: collection
entity: Payment
view { GETEntities }
path "/Payments()"
GET *-> payment
GET title="Order" *-> order
}
resource payment {
type: item
entity: Payment
view { GETEntity }
path "/Payments({Id})"
GET title="Order" -> order
}
resource PaymentAccepted {
type: item
entity: Payment
actions { CreateEntity }
relations { "http://relations.restbucks.com/payment" }
path "/Payments()"
GET --> payment (OK(payment))
}
}
}
Ready for service
Our shop is now ready for business. Let's start our server and POST an order. Using Postman POST the following entry, with Content-Type application/atom+xml to http://localhost:8080/responder/interaction-hateoas-restbucks.svc/Orders()
<?xml version='1.0' encoding='utf-8'?>
<entry
xmlns="http://www.w3.org/2005/Atom"
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xml:base="http://localhost:8080/responder/interaction-hateoas-restbucks.svc/">
<id>http://localhost:8080/responder/interaction-hateoas-restbucks.svc/Orders(1)</id>
<title type="text" />
<updated>2013-10-28T11:57:15Z</updated>
<author>
<name />
</author>
<category term="RestbucksModel.Order" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
<content type="application/xml">
<m:properties>
<d:size>abc</d:size>
<d:milk>abc</d:milk>
<d:name>abc</d:name>
<d:location>abc</d:location>
<d:quantity m:type="Edm.Int32">1</d:quantity>
</m:properties>
</content>
</entry>
You will receive the following response 201 Created:
<?xml version='1.0' encoding='utf-8'?>
<entry
xmlns="http://www.w3.org/2005/Atom"
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xml:base="http://localhost:8080/responder/interaction-hateoas-restbucks.svc/">
<id>http://localhost:8080/responder/interaction-hateoas-restbucks.svc/Orders(1001)</id>
<title type="text" />
<updated>2013-10-28T23:36:07Z</updated>
<author>
<name />
</author>
<link rel="self" type="application/atom+xml;type=entry" title="order" href="Orders(1001)" />
<link rel="http://relations.restbucks.com/update" type="application/atom+xml;type=entry" title="OrderUpdated" href="Orders(1001)" />
<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Payment" type="application/atom+xml;type=entry" title="Payment" href="Payments(1001)" />
<link rel="http://relations.restbucks.com/payment" type="application/atom+xml;type=entry" title="PaymentAccepted" href="Payments()" />
<link rel="http://relations.restbucks.com/cancel" type="application/atom+xml;type=entry" title="OrderCancelled" href="Orders(1001)" />
<category term="RestbucksModel.Order" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
<content type="application/xml">
<m:properties>
<d:milk>abc</d:milk>
<d:location>abc</d:location>
<d:name>abc</d:name>
<d:size>abc</d:size>
<d:Id m:type="Edm.Int32">1001</d:Id>
<d:quantity m:type="Edm.Int32">1</d:quantity>
</m:properties>
</content>
</entry>
Notice that you can pay this Order by using the 'payment' link:
<link rel="http://relations.restbucks.com/payment" type="application/atom+xml;type=entry" title="PaymentAccepted" href="Payments()" />
This implementation of the Restbucks API is a nice little Hypermedia API example, but it could be improved in a few ways. The first problem is how to get the initial Entry to post to /Orders. I prefer to coin a new link relation for this task e.g. http://relations.restbucks.com/new bound to /Orders/new. We could then default a few details and provide an Entry that could be filled out and POSTed back.
Another issue is the 'application/atom+xml' media type. Perhaps I would like a json payload. IRIS comes with a few different media type Providers, including 'application/hal+xml' and 'application/hal+json'. HAL is an xml or json media type suitable for Hypermedia API's because it specifies the all important syntax for links. The IRIS server can simply be configured with the HalProvider by modifying the spring-beans.xml as follows:
<bean id="halProvider" class="com.temenos.interaction.media.hal.HALProvider">
<constructor-arg ref="edmMetadata" />
<constructor-arg ref="stateMachine" />
</bean>
<bean class="com.temenos.interaction.winkext.RegistrarWithSingletons">
<property name="singletons">
<list>
<ref local="atomProvider" />
<ref local="edmxProvider" />
<ref local="serviceDocumentProvider" />
<ref local="errorProvider" />
<ref local="xhtmlProvider" />
<ref local="halProvider" />
</list>
</property>
<property name="serviceRoots">
<list>
<ref local="ServiceRoot" />
<ref local="Metadata" />
</list>
</property>
</bean>
<!-- Add dependency for our hal provider -->
<dependency>
<groupId>com.temenos.interaction</groupId>
<artifactId>interaction-media-hal</artifactId>
<version>0.4.0-SNAPSHOT</version>
<scope>runtime</scope>
</dependency>
With very little effort you could now use the HAL Browser to understand your API:
