Diploma Thesis final report

My master's study diploma thesis has been submitted. Here is the final report about outcome of my work.

My thesis analyses the REST architectural style and designs a testing and compliance tool (Java EE, JSP).

The final diploma thesis text can be downloaded here: https://dip.felk.cvut.cz/browse/pdfcache/haltulud_2012dipl.pdf

The source code of a testing tool (RESTfulChecker) is available here: https://github.com/lu2/RESTfulChecker

The testing tool (RESTfulChecker) runs here: http://ludva.tk:8080/RESTfulChecker/

Some notes relating to my masters diploma thesis can be found on my blog: http://lhaltuf.blogspot.cz/search/label/RADREST

The RESTfulChecker checking

The RESTfulChecker is working and can be accessed there. It is entry page with predefined tests, feel free to try it.

Current state of Diploma Thesis

Summary of my diploma thesis work.

What has been done
Programming:
RESTfulChecker is working, as per commit ecdd67c6e6 it's validating Uniform Interface (by building tree and  by validating HTTP headers) and Cacheability (by validating HTTP headers) constraints.
Asside of showing tree, it also shows each resource's response (by clicking on # sign) and OPTIONS response (by cliking on o sign).
It also showing result of validation (API is/is not RESTful) + prints REST violations for each resource.
No more REST constraints checking would be implemented (aside of questionnaires).

Writing:
So far all I wrote is here on my blog.

What needs to be done
Programming:
Correct/review implemented validation of 2 constraints.
Enhancing tool for REST testing by repeated testing capability. What about just allow to download xml with generated tree. Everyone can then compare this xml to expected xml? - work done?
Test it on something else then phprestsql.
Implements questionaiers for other 3 constraints, sixth (code on demand) is omited.
JUnits
Comments
Refactoring

Writing:
Mapping REST to HTTP analysis.
Finish RESTful API examples.
REST API description standardization.

What I am going to do now:
Start writing thesis for real (oficial text in LateX).
Learn myself to use OAUTH so I can acces more RESTful apis.
Find more REST APIs.

5weeks till handover.

REST constraints questionnaire

As I previously wrote in my blogpost about automatic testing of REST constraints we have some REST constraints we cannot test automatically against black box API. These constraints are:

• Client-Server
• Stateless
• Layered System

So here I am going to propose questionnaire for web developer which can tell us if his application satisfying these criteria. All of the questions should be answered by yes or no.

Note: by application I mean server application.

Client-Server:
Does your application providing service for other machines (clients)? yes
Is that service available to more then one client?  yes
Does your application listening and responding for request on that service? yes

Stateless:
Does your application keeping any context while communicating with client? no
Does the client keeping all the needed context while communicating with your application? yes
Is one client request enough for your application to create appropriate response? yes

Layered System:
Are you leading client to access some part of your server's resources directly by these resources low level api? (E.g. when you need to provide some data from mysql database, do you provide client access to this database so it can query demanded data by itself?) no

(Green are answers that indicating fulfillment of constraint.)

Current plan

What was done in last week:
HTTP requirements for responses.

What I am going to do next week:
programing:

• validation of responses as sumarized in link above,
• finish junits tests.

writing:

• propose questionnaires for REST constraints we cannot test (done)
• some REST/nonREST api review (here at google docs).

HTTP requirements for responses

Here I am going to make a summary of what is required in HTTP responses according to HTTP/1.1 rfc.
There are SHOULDs and MAYs in rfc, which I omit from  my table as I will check only required restrictions.
source: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10 :

response's status code	MUST NOT	MUST
204 No Content	include message-body
205 Reset Content	include an entity
206 Partial Content	include other entity-headers if the response is the result of an If-Range request that used a weak validator	include Content-Range header or multipart/byteranges Content-Type including Content-Range fields for each part. If a Content-Length header field is present, it MUST match the actual number of OCTETs transmitted in the message-body. Date ETag and/or Content-Location, if the header would have been sent in a 200 response to the same request Expires, Cache-Control, and/or Vary, if the field-value might differ from that sent in any previous response for the same variant
304 Not Modified	contain a message-body include other entity-headers if weak validator	include Date, unless its omission is required by section 14.18.1 ETag and/or Content-Location, if the header would have been sent in a 200 response to the same request Expires, Cache-Control, and/or Vary, if the field-value might differ from that sent in any previous response for the same variant
401 Unauthorized		include a WWW-Authenticate header field
405 Method Not Allowed		include an Allow header containing a list of valid methods for the requested resource.
416 Requested Range Not Satisfiable	response MUST NOT use the multipart/byteranges content- type

Table of contents for my diploma thesis

This is draft for my diploma thesis table of contents:

1. Motivation - taken partly from this, moved to testing.
2. REST constraints analysis - based on this.
3. Mapping REST to HTTP analysis.
4. REST constraints testing - based on this.
5. Some REST APIs examples.
6. Apps for REST testing - based on this.
7. Creating tool for REST testing - based on this.
8. Enhancing tool for REST testing by repeated testing capability (continuous integration?).
9. REST API description standardization.

 It is nice to see my diploma thesis is mostly writen :D

Czech language below is my outlines from my oficial diploma thesis assignment:

Analyzujte a teoreticky zpracujte mandatorní architektonická omezení, která definuje REST.
Která lze automaticky ověřit/testovat?
Současné aplikace pro testování REST.
Vytvořte nástroj, který vyhodnotí a otestuje RESTful API - SaaS.
Navrhněte a implementujte Web aplikaci pro opakovatelné testy.
Navrhněte standardní popis REST API

Current state of RESTfulChecker

Current state of my project RESTfulChecker as of this commit is:

CheckAPI is now able to build trees of RESTful API. Please note that it prints maximum of 10 entities of collection.
You can try it for example with phprestsql: http://phprestsql.sourceforge.net/tutorial/
with header Authorization: Basic cDEyNjM3MXJ3OmRlbW8=

My diplomaThesis plan for next few weeks

11.5.2012 is deadline for my diploma thesis hangdover. That is less then 9 weeks.
So my work-plan is as follows.

Programing part:

• in 7 days make my app RESTfulChecker build trees of selected API (done),
• in 14 days implement junit tests in reasonable quantity.

Writing part:

• in 7 days create table of contents for my diploma thesis (there),
• in 14 days propose questionnaires for REST constraints we cannot test (done),
• in 14 days create tables with overviews of HTTP request-response allowable and required headers (done).

Current state of RESTfulChecker

Current state of my project RESTfulChecker as of this commit is:
You can use HTTP client, or check API.

Http client is just helper, it won't be visible in future versions but for now is fairly operational. You can send customized HTTP requests with it and it will show responses for you.

Check API is main thing in RESTfulChecker and its on starting point now. You can try accessing some REST API with it. So far it tries to access remote API by GET method. If it succeeds (judged by response code 200) it parse response for hrefs and show them (which is now strangely bugged - hrefs are found properly, but they are "doubled" somehow - gotta repair it first).
Secondly, when it won't succeed because of 401 Unauthorized - it provides you with an option to specify authorization headers - for example for site RESTful database you can do that by this header:
Authorization Basic cDEyNjM3MXJ3OmRlbW8=
which is basic authorization based on Base64 coding of string containing user:password

Making GAE app run on Tomcat

Today I'll tell you how to run your Google App Engine Java application on Tomcat server.

The situation:
You made yourself Google App Engine (GAE) project in Eclipse using Google's plugin. You can now run it locally from Eclipse or deploy it to Google to run it online. But what if you want to run it somewhere else, perhaps in your own Tomcat server?

If you don't use Google's specific API in you app, you can very easily run you GAE/GWT app in other servlet container such as Jetty or Tomcat. I am going to focus on Tomcat.

Method 1:
If you just want to deploy your app on Tomcat once a while, you can grab war folder from your project and copy it into Tomcat's webapps directory. Restart Tomcat and it should load the app automatically.

But when you developing an application and deploying it to your Tomcat server repeatedly you wouldn't like to manually copy war folder with every change in source code right?

Method 2:
Fortunately you can make Eclipse to do it for you. You just have to transform your GAE project into faceted form:

1. In Eclipse - right click your project root folder. Choose Configure -> Convert to Faceted Form.
2. Tick Dynamic Web Module and on the card Runtimes tick Apache Tomcat.
3. Click Further configuration available....
4. Write war into Content directory.
5. Click OK.
6. Click OK. Eclipse then convert your project and after that you can right click your project, choose Run As -> Run on Server and enjoy the autobuild and deploy on Tomcat.

Of course mentioned recipe suppose that you know how to install and set Tomcat and how to add it into Eclipse.

GAE doesn't support HTTP OPTIONS method.

1.March update: There is new issue at GAE tracker  related directly to OPTIONS. Feel free to star it if you want that feature to be implemented.

During work at my java project RESTfulChecker, I reached a point where I needed to send OPTIONS HTTP method from RESTfulChecker to the remote API. OPTIONS method is defined in rfc2616 along with other HTTP methods such as GET, POST, PUT etc and is vital for REST. RESTfulChecker is running at Google App Engine, which is Google's cloud based solution for hosting (not only) Java apps. However upon building OPTIONS request I ran into following exception occurring when executed on Google App Engine:

java.net.ProtocolException: OPTIONS is not one of the supported http methods: [GET, POST, HEAD, PUT, DELETE]
    at com.google.apphosting.utils.security.urlfetch.URLFetchServiceStreamHandler$Connection.setRequestMethod(URLFetchServiceStreamHandler.java:142)
    at tk.ludva.ConnectionTestServlet.doGet(ConnectionTestServlet.java:18)
    at javax.servlet.http.HttpServlet.service(HttpServlet.java:617)
    at javax.servlet.http.HttpServlet.service(HttpServlet.java:717)
    at org.mortbay.jetty.servlet.ServletHolder.handle(ServletHolder.java:511)
    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1166)
    at com.google.apphosting.utils.servlet.ParseBlobUploadFilter.doFilter(ParseBlobUploadFilter.java:102)
    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1157)
    at com.google.apphosting.runtime.jetty.SaveSessionFilter.doFilter(SaveSessionFilter.java:35)
    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1157)
    at com.google.apphosting.utils.servlet.TransactionCleanupFilter.doFilter(TransactionCleanupFilter.java:43)
    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1157)
    at org.mortbay.jetty.servlet.ServletHandler.handle(ServletHandler.java:388)
    at org.mortbay.jetty.security.SecurityHandler.handle(SecurityHandler.java:216)
    at org.mortbay.jetty.servlet.SessionHandler.handle(SessionHandler.java:182)
    at org.mortbay.jetty.handler.ContextHandler.handle(ContextHandler.java:765)
    at org.mortbay.jetty.webapp.WebAppContext.handle(WebAppContext.java:418)
    at com.google.apphosting.runtime.jetty.AppVersionHandlerMap.handle(AppVersionHandlerMap.java:249)
    at org.mortbay.jetty.handler.HandlerWrapper.handle(HandlerWrapper.java:152)
    at org.mortbay.jetty.Server.handle(Server.java:326)
    at org.mortbay.jetty.HttpConnection.handleRequest(HttpConnection.java:542)
    at org.mortbay.jetty.HttpConnection$RequestHandler.headerComplete(HttpConnection.java:923)
    at com.google.apphosting.runtime.jetty.RpcRequestParser.parseAvailable(RpcRequestParser.java:76)
    at org.mortbay.jetty.HttpConnection.handle(HttpConnection.java:404)
    at com.google.apphosting.runtime.jetty.JettyServletEngineAdapter.serviceRequest(JettyServletEngineAdapter.java:135)
    at com.google.apphosting.runtime.JavaRuntime$RequestRunnable.run(JavaRuntime.java:422)
    at com.google.tracing.TraceContext$TraceContextRunnable.runInContext(TraceContext.java:449)
    at com.google.tracing.TraceContext$TraceContextRunnable$1.run(TraceContext.java:455)
    at com.google.tracing.TraceContext.runInContext(TraceContext.java:695)
    at com.google.tracing.TraceContext$AbstractTraceContextCallback.runInInheritedContextNoUnref(TraceContext.java:333)
    at com.google.tracing.TraceContext$AbstractTraceContextCallback.runInInheritedContext(TraceContext.java:325)
    at com.google.tracing.TraceContext$TraceContextRunnable.run(TraceContext.java:453)
    at com.google.apphosting.runtime.ThreadGroupPool$PoolEntry.run(ThreadGroupPool.java:251)
    at java.lang.Thread.run(Thread.java:679)


The exception is caused by this part of my code:

URL remoteUrl = new URL(apiUrl);
HttpURLConnection conn = (HttpURLConnection) remoteUrl.openConnection();
conn.setRequestMethod("OPTIONS");

Namely by conn.setRequestMethod("OPTIONS"); We can see from Stack Trace that the exception is raised by Google's URLFetchService. As far as I know, every request sent from your GAE application have to pass through that URLFetchService so unless it supports OPTIONS we are unable to send that request from our GAE apps.
We can check googleappengine's source and this part of urlfetch can confirm us about supported methods.

I found a posts related to this problem at GAE group but at the time of writing this blogpost, it's without reply:
Limited HTTP method on urlfetch API - need OPTIONS, PROPFIND ... by Wingi.
People want WebDAV suppport, there is even ticket in GAE's bugtracker for it.
Because mentioned post is about WebDAV's methods, I added my own dedicated to OPTIONS method only: OPTIONS is not one of the supported http methods?

If you know the solution for sending OPTIONS from GAE, kindly let me know or discus in threads mentioned.

My project: RESTfulChecker on GitHub and GAE

First lines of my RESTful test tool has been written and it is time to share it. So for my colleagues and all who is interested, the sources of my project called RESTfulChecker is available at GitHub: https://github.com/lu2/RESTfulChecker

Also the dev version of my project is currently running at Google App Engine at the adress: http://restfulchecker.appspot.com/ http://ludva.tk:8080/RESTfulChecker/

Please note that my project at above links is work in progress so it may contain bugs, doesn't present intended functionality, or not be operational at all. Use it at your own risk - I do not bear any responsibility if it will detonate your computer (or head).

Anyway if you have any notes related to my work let me know. I would be happy to know your opinion.

Quick overview of Mingle

In this blogpost I am going to take a quick look at the Mingle by ThoughtWorks to provide a brief summary of what this software tool is.

Definition of Mingle from the authors: Mingle is an Agile project management solution that offers unparalleled visibility into software initiatives and unprecedented collaboration among business and delivery teams.

When multiple teams are working on a software product, they need to cooperate together. They need a way to communicate and track their progress. Mingle is a tool for such team collaboration. It's based on (virtual) cardwals, swimlanes and cards. Swimlanes on cardwals represents the stage of developing. Card represents a task, request, or some small unit of work that needs to be done on the project. By moving the card through swimlanes, we can track its progress easily. If some team needs to communicate about a task, they just write their questions or informations on that card. Cards can be organized into groups and trees allowing its easy prioritizing or breaking to smaller tasks. If you need some statistics and metrics of your project then of course Mingle can generate them for you.

Requirements for running Mingle as of v3.5 (taken from Mingle documentation):
Clients accessing Mingle through web browser (Firefox and Safari are recommended).
Server side of Mingle requires PostgreSQL or Oracle database.
The recommended HW configuration for server side is (~40-50 users):

• CPU: Quad Core, 2 GHz (or higher)
• Disk: 5GB Initial, regular monitoring and backups recommended based on usage.
• Memory: 2 GB RAM, of which 1 GB can be dedicated to Mingle

Pricing
Mingle is priced by per-user cost. (First 5 users are free). There is also ability to obtain community license for other users under circumstances stated here.

Pros:

• organizing tasks in trees and groups,
• eye catchy yet clean user interface.

Cons:

• high server hardware requirements,
• only 5 users are free of charge.

Just a little note at the end. ThoughtWorks was behind software: CruiseControl and Selenium.