REST API simplified

Before I get philosophical, here is the gist:

For the function:

• getPhoto(String photoName, int userId, int width) 

In the controller:

• PhotoController.java 

The suggested rest API is:

• http://hostname.com/api/photo/get?photo_name=flower&user_id=123&width=1024

Or in more general terms:

• {protocol}://{domain}/api/{controller_or_service_name}/{short_function_name}?param1=value1&param2=value2&paramN=valueN

Philosophy

I've worked with dozens of rest API's and also created a few. Some conventions are very simple and easy,  some are complex.

When creating an API you have three players to think about:

1. The developer (probably you)
2. The client developer
3. The end user

The developer (you)

You are your own client, and so are the developers that will inherit and maintain your code. Creating a self-explanatory API means making it easily expandable.
If you are developing a service layer or a controller layer, I suggest adding their name to the path, right after the host:

• host.com/photo/

This will make it easy to to find the right controller when maintaining the code. This will also, usually be, either the object that the function returns, the main object that it manipulates, or the name of the main action, in that order of priority.
For the same reason, immediately after, put the short name of the function that handles the parameters:

• host.com/photo/get 

Then come the query parameters themselves:

• host.com/api/photo/get?photo_name=flower&user_id=123&width=1024

Non abiding order, optional and nullable.

The client developer

If you only had the client on your mind, using query parameters for everything would be the best choice, their order is non-abiding and they are all optional. But this will require creation of a special function for navigating to the right controller and make it imparseable to the user.

The end user

If you were only to think about the end user, you would probably use very few query parameters (e.g. id=123) and mostly path sections (e.g. photo/id/123). Path sections are cleaner looking and use one simple delimiter character ("/"), so users have an easier time navigating your API. But this is where user simplicity ends, and developers' complexity begins:

1. Using a path for dynamic data like a user's id could cause some trouble:
• if the function can handle a null value
• if it includes special characters.
2. The order of the parameters is static and the client developer can't just throw them on using a query parameter map.
3. Arrays and JSON objects can't fit in a path.

To sum it up:

• http://hostname.com/api/photo/get?photo_name=flower&user_id=123&width=1024

Or in more general terms:

• {protocol}://{domain}/api/{controller_or_service_name}/{short_function_name}?param1=value1&param2=value2&paramN=valueN

And here are a couple additional examples:

• Function: deAssociateUserAndPhoto(String userId, String photoId)
  API: http://hostname.com/api/user/deassociate ?photo=456 user=123
• Function: MapService.getDistance(Point a, Point b)
  API: http://hostname.com/api/map/distance?point_a=42.365,31.987&point_b=36.743,28.234

The real difference between static and dynamic programming languages

The real difference between static and dynamic programming languages from an entrepreneur's point of view.

The debates are endless and tiring, you can get a taste at stackoverflow.

But when push comes to shove, and you really want to know what is the actual real-life difference between statically typed (aka Java) and dynamically typed (aka python) programming languages...

It all comes down to this simple explanation:

• Dynamically typed = Easy Get up
• Statically typed = Easy Maintenance

When using dynamically typed languages, you are much faster in constructing a new project, and you need less lines of code than a statically typed language to do most things. Later on, when you'd want to poke around and change stuff, it would probably be harder.

When using statically typed languages, it's easier to maintain, change and refactor the code, but you have to do more work to get things going.

For example, defining and sorting a list:

Java (static):

List<integer> a = new ArrayList<integer>();
a.add(5);
a.add(2);
a.add(3);
a.add(1);
a.add(4);
Collections.sort(a);

python (dynamic):

sorted([5, 2, 3, 1, 4])

As you can see, Java (static) is longer to type and you have to know about many keywords, pyhton (dynamic) is much shorter and self explanatory...
But if one day, you would want to change some of the objects in the list, and accidentally put a "text" object instead of a "number":
python would just handle it and treat all of the objects in the list as text objects. You would only find out about your mistake when the program runs and a human actually looks at the output and realizes something is misplaced.
Where in Java, the program will not even run, so you would know immediately where and what to fix.

You can say that python is "smarter" because it adapts to the data, and you would have a point... but when you have thousands of lines of code, and many programmers, you want zero flexibility and you want to be notified of any inconsistency.

So to sum it up:
If you want speed at the beginning, use a dynamic language.
If you want easier long-term maintenance, use a static language.

What do you think? comments/corrections are welcome...