How to Design a RESTful API
Posted by Khaled Hussein in Cool Hacks, Open Source Projects, Programming, Research on May 25th, 2009
In order to understand how to design a RESTful API, you need to understand the
concepts behind REST. The next section explains REST briefly.
What is REST?
Scalability and performance are two of the main concerns when developing
hypermedia systems. Roy Fielding introduced an architectural style for
distributed hypermedia systems that focus on minimizing latency while
maximizing scalability. The introduced architecture leverages a number of web
standards such as HTTP. In this architecture, a client sends a request to a
server to retrieve a specific resource. Then, the server responds back with a
specific representation of the requested resource, which puts the client in a
specific state. In other words, the client transfers its state to a new one
with each resource request. Hence, Roy Fielding named his architecture as
Representational State Transfer (REST).
So, what is a resource?
A resource is an entity that can be requested from client applications.
Usually, resources are nouns such as “BookTitle” and “ActorName”. When I think
about resources, I try to model the system using object oriented principles.
Then, the resources are basically the classes and objects, which are never
verbs.
Since REST is based on HTTP standards, it maps each resource to a URI. For
example,
http://example.com/books/01-23-45-67-89/BookTitle
The server can send different representations of the same resource, depending
on the request. For example, the client can ask for XML or JSON representations
among others. It is always recommended that the resource representation can be
validated against some sort of schema
Note that URIs represent tree hierarchies, but it doesn’t have to be the case.
For example, to represent a book in a specific section in a particular library
you could do,
http://example.com/libraries/LibraryName/sections/SectionName/books/BookName
So, what if you need to represent a resource that isn’t in a tree hierarchy.
For example, if you would like to represent a point in an image using X-Y
coordinates. Lets assume that X=20 and Y=30. It doesn’t make sense and it is
definitely not intuitive if you design the resource like this:
http://example.com/image/12345/point/20/30
But you could do,
http://example.com/image/12345/point/20,30
The book named “Restful Web Services” by Leonard Richardson and Sam Ruby is a
wonderful source to similar URI tips. I highly recommend going through this book
before you get into business.
Interacting with resources
REST identifies a resource as a URI and the operations on this resource are
HTTP methods. Although there are a number of HTTP methods, GET, POST, PUT, and
DELETE are the most common ones. GET and DELETE don’t need explanation, but
POST and PUT are sometimes tricky. The confusion comes from the wording of the HTTP RFC for the methods. So, here is the deal.
You can use PUT and POST to create/modify the resource. The difference is that
you use POST if the client doesn’t know the final URI for the resource and use
PUT if the client knows the final URI of the resource. Let me demonstrate with an example.
Example 1:
Lets assume that the resource design is as follows:
http://example.com/books/<ISBN>
To create and/or modify a book the client should use PUT on this URI.
Example 2:
Lets assume that the resource design is as follows:
http://example.com/books/<generated-id>/<BookName>
In this case, the client doesn’t know the URI because it doesn’t know the
generated-id for the book to be created. Therefore the server should provide
another URI to be hit with a POST request such as
http://example.com/books/<BookName>
The server should return the final URI of the book in its response to the POST
request from the client application.
Steps to design RESTful API
- Identify resources and URIs.
- Resources should be nouns.
- Try to make the URI intuitive and easy to guess.
- If in doubt, map it to object oriented system.
- If still in doubt, ask for help.
- Identify resource representation formats.
- A resource can have one or more representation such as (JSON, XML, …etc).
- Always have a schema to validate your resource representation against.
- Identify supported HTTP methods.
- Don’t use an uncommon HTTP method that may not be supported by the client application.
- Use PUT when the client knows the final resource URI and use POST otherwise.
- Use GET to get a specific representation of the resource.
- Use DELETE to get rid of the resource :).
- Try to make your implementation idempotent.
- Identify resource returned status codes.
- Always use the standard HTTP status codes.
- Always provide a return message to provide more information about the returned status.
Happy coding
Please, share your thoughts !!
Linux command line repository
Posted by Khaled Hussein in Cool Hacks, Linux, Open Source Projects, Programming, Shell on March 20th, 2009
Here is another command line repository. It has a bunch of one line commands that we maybe using everyday. You can also comment and vote on these commands.
Happy coding
Please, share your thoughts !!
Linux Virtual Terminals
Posted by Khaled Hussein in Cool Hacks, Linux, Open Source Projects, Programming, Shell on March 16th, 2009
As you all know, linux is a multi-user system. This means that you can login as two or more different users at the same time. To switch between virtual terminals, you can use the keyboard combination (Ctrl-)Left Alt-FN, where N is in range 1-12).
You can also switch to any virtual terminal from the command line using chvt
chvt 5
Switches to the virtual terminal number 5.
Happy coding
Please, share your thoughts !!
Bash command line editing using vim
Posted by Khaled Hussein in Cool Hacks, Linux, Shell, Vim on February 19th, 2009
I was thinking that it’d be really cool if there is a way to edit my bash shell commands using vim. So, one of my friends told me about a pretty cool command called fc. It is basically a way to fix your last run command in a text editor like vim. All you have to do is to type fc in the command line. Then, you can use vim to type whatever command you want.
After a little bit more of research, I figured that you can do the following:
set -o vi
This will enable you to use vim editing facilities at the command line itself. Just hit Escape and you’ve got vim at the shell :).
Happy coding
Please, share your thoughts !!
Change GTK+ theme from command line
Posted by Khaled Hussein in Cool Hacks, Linux on February 19th, 2009
First, you need to know that installing a gtk theme from command line is fairly easy. All you have to do is to extract the contents of your theme tar file in /usr/share/themes.
tar -zxf your-theme-.tar.gz /usr/share/themes/
So, to switch your theme, you can install a tool called gtk-theme-switch. It is easy to guess :).
sudo apt-get install gtk-theme-switch
Then all you have to do is to use this tool and provide it with the path to your theme. For example:
gtk-theme-switch2 /usr/share/themes/GlassyBleu
Happy coding
Please, Share your thoughts !!
Change keyboard layout from command line
Posted by Khaled Hussein in Cool Hacks, Linux on February 19th, 2009
I don’t want to start a debate about the best keyboard layout ever. However, I was pretty much open minded and decided to give Dvorák a try. I used it for a few months and I caught up with my original speed of qwerty.
To switch your keyboard layout to Dvorák:
setxkbmap -layout dvorakHonestly, I feel more comfortable typing in Dvorák now than qwerty. However, if you want to keep using qwerty, here is how to change your layout back to qwerty:
setxkbmap -layout usFor the past a few months, I practiced using a different variant of dvorak. It is called programmer
Dvorák. Actually it is pretty nice, since it saves time with all the special characters and such.
So, to use this variant all you have to do is:
setxkbmap -layout us -variant dvp
Also, because I use vim all the time, I mapped the Caps Lock key to Escape. This makes it so much
easier to use Esc without jumping all the way to the Esc key. To do that, you can create .xmodmap
file in your home directory. Then copy the following in it.
1 2 | clear Lock
keycode 0x42 = Escape |
And this is all what you need to change the key mapping. Now, all you have to do is to put this into
effect using xmodmap as follows:
xmodmap ~/.xmodmap
happy coding :). Please, Share your thought !!
Eclim is Eclipse for Vim Lovers
Posted by Khaled Hussein in Cool Hacks, Programming on November 26th, 2008
Eclipse is a powerful open source IDE. It is designed in a very extensible fashion that makes it attractive for software engineers to experiment with it. A few months ago, I started writing a number of Eclipse plugins. When I used Eclipse as my IDE, I liked a number of cool features such as automatic management of the package imports, some code refactoring snippets, automatic compilation, smart auto completion… etc.
Vim is one of the most powerful editors if not THE most powerful. It is very light weight. There is a huge community support for it. You can pretty much find plugins for most desired features. And if it isn’t implemented, it is easy to write it yourself.
Personally, I think it is unfair to compare Eclipse to Vim because this would be comparing oranges to apples; IDE to an editor. However we can definitely argue that Vim can be compared to Eclipse editing features. In this case, (for vim lovers like me) Vim wins for multiple reasons that I won’t list here because I don’t want to go into this war. So, how can we use Vim but also use the powerful IDE features?
Well, among other solutions, Eclim is just what I was wishing for. Eclim provides the best of both worlds. It enables vim to use features of a headless Eclipse. So, you still use vim to edit your files but you also get all the previously mentioned cool stuff. It is definitely worth a shot. I am going to use it in my next real Java project and I’ll inform you of my opinion after realistic use.
Let me know, what do you think.
Program Query Languages
Posted by Khaled Hussein in Open Source Projects, Programming, Research on November 25th, 2008
Needless to say that query languages have gained a huge success across various application domains, especially business related solutions. Query languages are simple languages that are intended to facilitate making queries against repositories of resources such as data or information. For instance, most business applications use some sort of data storage such as a database or XML which can be easily queried against using SQL and XPath respectively.
The thing about query languages is that it enables programmers to describe the problem rather than how to solve it. This fact inspired a number of researchers to look at programs and source code as resources to be queried. As a result a new kind of query languages showed up called program query language. The purpose of program query languages is to enable programmers to make queries against:
- Source code such as ASTLog and JTransformer. (Static Analysis)
- Running Programs. (Dynamic Analysis)
- Both such as SOUL, PQL, and .QL. (Hybrid)
Programmers and researchers have found a number of substantial uses of program query languages. One of the most important uses is finding bugs and errors, especially the runtime ones. For example, forcing code practices, such as closing a stream after it’s been used, is hard to detect. However PQL uses a very simple query to detect such a problem among others.
For those of you who understand by examples, click here for examples from the proprietary .QL language website. Also, don’t forget that PQL is the open source alternative.
So, tell me what do you think about program query languages? would you use them? what for? are they really usefull as their authors claim? Please, share your thoughts
Test Driven Development: Testing Private Methods Using Aspect Oriented Programming
Posted by Khaled Hussein in Agile Methodologies, Aspect Oriented Programming, AspectJ, Cool Hacks, Test Driven Development on September 26th, 2008
Recently, I have been working on a project that can be considered my first real test driven development experience. As the name implies, test driven development is an agile methodology that aims at producing code that has been fully tested. Another one of the most powerful advantages of test driven development is that if a developer modified the code, he can easily run the existing test suits and he would know if his modification broke any of the existing features in the code. Essentially, a developer starts thinking of the functionality that needs to be added to the existing code base. Then, before writing any code, he writes a test case (maybe a number of them) that will of course fail because the feature isn’t implemented yet. Then he would write the bare minimum code that would make the test cases pass. Then write more tests, then write more code to pass the tests …etc.
So, what’s the problem? Well, one of the main problems with Test Driven Development is testing private methods (assuming that you’re using an Object Oriented language). I googled the problem, and I found a number of solutions. Here is a list of the interesting ones along with the problems of each:
- Change the access modifier of the method to public/protected/internal/…etc., run your tests, then change it back to private
- Once you change the access modifiers back to private, your test cases won’t even compile.
- If I decided that a specific method needs to be private, why would I ever want to change it to public. It seems like a dirty walk around the problem and violation to the developer’s intended design.
- Philosophical solution: Test only public methods, which are assumed to call private ones.
- It is based on the unsolved debate of what unit testing really is.
- It sounds like “lets ignore the problem intentionally”
- If you’re using JUnit4, you can create your test cases in the same class you’re testing, which means you have access to its private methods.
- It results in a large sized release of your project. Because you have all test cases embedded in your code.
- What if your test case needs to test two private methods separated in two different classes?
- Use annotations/attributes/…etc.
- It isn’t a language independent solution
- Behind the scenes, these annotations change the accessibility of your methods. But again, this implementation is different in each language.
- I’d appreciate it if anyone shares any other solutions?
Luckily, I was able to find another solution that seems to satisfy my requirements. Although the solution is generic and language independent, I’ll explain it referring to Java. Before we go on, let me give you a quick introduction to the technologies that I used.
Aspect oriented programming is a technology intended to motivate separation of concerns. Usually developers refer to concerns as features that can be, but not necessarily, tied to the business logic. For example, logging, caching, exception handling, …etc. However, I think that it is safe to look at concerns as any feature that is required in your program. One of the most powerful tools that aspect oriented programming provides is called introduction. Basically, it means that you can introduce new fields, methods, or structure to your existing classes, which is the core tool behind my solution. [Have you guessed the solution yet?] Most language compilers have aspect oriented programming extensions. For example, AspectJ is one of the most common Java extensions that supports aspect oriented programming.
Alright here is how you can unit test private methods using aspect oriented programming:
- Create aspects that introduce public methods to the class under test
- In those public methods, you have access to all private methods and fields, call the private method and return the result.
- In your unit test, call the public method which is just a simple wrapper to the private method.
- Once your program is mature and ready to release, all you have to do is to build the source code without both of unit tests and AspectJ files.
Is it the best solution in the world? I don’t think so, and here is why:
- If I ever wanted to release my test cases as well as my source code, I have to ask other developers to install a new compiler, because the test cases won’t compile without applying (weaving) the aspects into the code base. In my case, the compiler is AspectJ.
- Developers in my team have to learn a new language constructs (aspects). However, I have to say that you can learn it in less than an hour. Probably, not master it ;).
Note: if you know of anyone that proposed this solution, please let me know so that I give him the credit for the idea. Also let me know if you’d like any sample source code to demonstrate the idea.
Please, share your thoughts!
Personal Scrum Experience
Posted by Khaled Hussein in Agile Methodologies, Personal on September 11th, 2008
Recently, I was involved in a number of projects that used Scrum. Just in case you don’t know, Scrum is an agile software development methodology intended to improve communication among team members. When using Scrum, each project has a backlog that contains all the goals and tasks that need to be accomplished. Team members start off with a sprint planning session. During this session, team members pull tasks from the backlog and put them into a so called sprint. Generally, sprints last 2 or 4 weeks and in this time, team members are committed to finish the tasks within the sprint. The most attractive part about Scrum is its daily meeting/stand up feature, in which team members (actually stand up) and answer 3 questions; (1) What was done yesterday? (2) What’s going to be done today? (3) What barriers are faced, if any?
A few days ago, it hit me, ‘Hey, why don’t I modify Scrum a little bit so that it can be applied to my personal life?’ Since then, I started researching previous experiences that used Scrum in different domains. Surprisingly, I found many altered uses of Scrum, which encouraged me to pursue my idea. For example, Michael Hicks and Jeffrey S. Foster, two computer science professors in University of Maryland, adapted Scrum to manage their research groups, rather than traditional software development; their modified version is called SCRAM.
This past Monday, I started jotting down my backlog, which will definitely continue to be modified and improved over time. I also decided to conform to the following scheme for my personalized SCRUM:
- Each sprint should be completed within 1 week.
- Sprint planning should occur every Sunday evening.
- My daily stand up (comedy session??) should be conducted every night before I go to bed.
I have been applying this personalized Scrum for a few days now, and it’s been going pretty well, thus far. I’ll keep you informed with my critiques and thoughts every month until I stabilize everything.
Please share your thoughts!!!