Betim Drenica

Ideal REST API design

2015-03-09T09:20:00+00:00

Introduction / short history

In mobile (tablet is included) era REST eclipsed SOAP in terms of web services. And, if we see and analyse in details both architectures (respectively architecture styles), and get environment constraints get just data what I request instead of “two hundred pages manual what I will get” is great, practical and useful. Imagine a mobile user using mobile data to get ten most popular books and consuming a SOAP service, just getting WSDL will push that month’s data invoice to limits. But coming from SOAP, with a commodity and many things defined for years, REST APIs have open a lot of debates in almost all aspects REST tends to resolve, make solution. So, after all years in designing (and consuming a lot) REST APIs I did a list of things I consider an ideal rest api design should contain.

Media types

Every Web API must support several media types but two are considered un-avoided, XML and JSON. Because of a latest momentum of HTTP programming and following standards JSON tends to be the most preferred and for this reason should unequivocally be default media type.

But XML has its own place, because of its robustness to present very complex scenarios and history (SOAP), if we can consider like this.

Partial results

If your API will be popular and you’re exposing big objects you will face situations in a big number of scenarios where there’s no need to get all fields of a resource, and if your api will support partial results will be a good benefit for consumers. Let’s take an example of countries resources, you will have an id, name, description, date added, status, shortcode, flag, etc. Most frequent scenarios when applications needs to display the resource are just Id (for internal relations with other information), name and possible flag, all other info you have / need for youself. But this, of course will come with a price in you infrastracture because querying will take longer and needs more resources (hope you will do something with caching).

Caching

Caching will save your life. Caching will destroy your life. And balance is caching is great feature for your api but will come with a price. As API designer I am big fan of caching while in your applications there are frequent scenarios when some tertial information is changing so rarily. I would favor a lot client caching vs server, but both are positive. The mechanism will improve execution time and a lot of related resources.

Security

Web API must be secured properly to resist “desire” of unauthorized people to access it. Web API must maintain a list of all developers / applications that are allowed to access API in a persistent location and check that list for every request. Access keys and roles must be very desired to assure that everything is under control. We have seen a lot of scenarios in the net when “some fields” that were not planned to be visible, were accessible through APIs but not through regular websites or official apps. If you’re designing APIs for your company that will be consumed by your applications, (and for scalability of these scenarios) applications are developed by other groups (in or outside your company), I saw a below design of security part in terms of accessing and roles must be in place.

Access Key

Web API must be accessible just using a key, unique key. Every combination developer / application must have its own key.

Roles (in backend)

According to my experience I found an API must support user roles. Below are roles I think it could have an API.

User

User role are for all users. Let’s say application users. They have access to all features of the API, but they can operate just in their resources, like UserId = 13 can do operations just for this Id but no others.

Administrator

Administrator is a powered role (but not most powered). It can do all operations for all users but not remove other admins or change the ownership of the API (add or remove super administrators). Admins are not allowed to create developer keys or to remove others from admins role. Either they have access to execute all methods of a resource.

Super Administrator

Super Administrator is most powered role in API. It can do everything.

Viewer

This role is just for auditing. It can just make selections, no post, no put, and no delete.

But if your api is public / not directly for you company roles tends to be not good fit, so consider other mechanisms of security. Nowadays OAuth2 and other mechanisms tend to be a very good choice to implement, and tokens are first citizen in these scenarios.

Versioning

Versioning of APIs is an interesting topic and there are several forms that you can achieve a good solution in this scenario. It could be great if you resist to time in terms of applying good architecture and analysis and the need for new versions of your APIs is reduced. But this is totally un-avoided situation so you have to have in place and plans.

I am fan of url versioning over header practice. In the first solution you have to tell in url the version of resource you’re looking for and server will answer accordingly to its existence with a falldown to an existing one if you try to play with numbers. In other side, second solution is, that url of resource always stay the same, but you mention in header version of the resource and server will respond accordingly. While version is not in place as header term is a little bit more complicated to be sent by applications while in my experience that developers always tend to make GET requests as simple as the can.

Constraints

Throttling is a must have mechanism that every API must implement. Imagine if an application will send millions of requests in minute to your backend, servers will go on fire. So, with constraints in place you can control them and direct to your pool accordingly. I am big fan of IP, client, number of request and any other meaningful throttling mechanism in terms of controlling requests made by clients. I am not fan of blocking app but just letting it wait for a period of time until the server are relaxed of course just if the accident is not repeated.

Tracing

Web API must support real-time tracing or logging of all operations that are executed. And this could be very helpful for developers to see requests sent by applications / client.

Documentation

Web APIs must be documented properly. And this is a key in success of API even before many other features. I’ve seen a huge number of great APIs that lack in documentation and failed to get to the point they planned. Why? Because, naturally no one knows how to use and what to use properly when you don’t tell what you’ve built behind. A proper documentation would be instructions for authorization, authentication, sending all popular methods (GET,POST,PUT,DELETE) in as many platforms as you imagine your API will be used (all programming languages, OSes, if needed, etc). As hospital as you’re with people that implement / communicate with your API, as much success you will have. And documentation and sampling is a key in this flow.

These paragraphs I wrote above are from my experience and wanted to share with you, dear reader, and it would be great to have your comment in:

what’s great API according to you?
mention two or three APIs you like? Why?

SMUP - Simple Math Under Pressure

2014-09-08T10:44:00+00:00

This is my latest app / game in Android (Google Play) and iOS (App Store).

Everything started as a test from an article I read that you can't do even simple math under constant pressure. I did several tests, and it became a small but cute app I decided to put in store.

App starts with a simple screen with message that you can't do simple math under pressure.

And touching a button it starts magical display of numbers with two possible answer you have to decide within seconds.

If you can't manage to answer in time or touch the wrong answer you simply loose the game, seeing result if your record is broken achieving more stages (spending more time in game answering right results).

Game has gained a lot of traction at very beginning of the its life and I am very happy for this fact. I hope it will be used by people to start the day, getting up their brain with simple math because it worths.

So, get the app, give it a try and stick to it until you beat your last record.

My Sunday experiment - Salaam in Android

2014-07-29T18:21:00+00:00

Last weekend I decided to jump in a personal challenge, to write a working version of popular last hit Yo in less than a day, using native Android tools (Java and Android Studio) with knowledge got from Xamarin (the super awesome mobile cross platform that use C# as main language). And the result is …. download from link below

Thanks to Parse as very powerful backend (cloud) platform I had Push Notifications as a gift / for free, users / logins to and many more. Really appreciated the fluent API that was readable and very productive. Needed just to get an idea and immediately started to use it without a single problem! Good job Parse. For sure I will be your customer!

Android Studio was very solid tool and made my life easy, to manipulate resources, layouts and write Java code. It’s code completion feature that was killer feature for me (imagine, coming from Visual Studio in this piece it must stay strong or move, while VS rocks in this part).

Coming to app part, it looks a simple apps with just few screens but it has some interesting features that it worths to take a try!

While we are in very interesting time (history perspective) I decided to use a famous word from arabic Salaam (read in wikipedia for this) that has more than a meaning of Peace, but first you can stick to it! So, I wanted to make easy for people to spread easily peace to each other!

So, idea is veeryy simple, add friend (username / name) who has the application, tap on it and send Salaam! If you put a non-existent friend (in application) it removes from your friend-list, either it will try to touch him / her with a message.

If you tap in your name you have all settings, email, ability to change passcode and some info.

If you logout you will lose friend list and stats while everything is saved locally! Don’t worry you can redo it easily :D.

Here are screens of Android version and I am planning to jump in iOS version challenge to (next sunday :D I hope).

Living in fast-times

2013-10-02T10:10:00+00:00

We all know (and feel) we’re living in time that’s going fast, and even faster every single day. And as part of this planet I was indeed in need to forcibly find ways to do things faster (like be up2date with technology), especially reading (books) and watching (educational videos). I need reading books because of programming, and according to my opinion if you don’t read you’re out, but if you don’t read at least 5-7 books per year I doubt in your ego to be good in this occupation, sorry, passion, and 10-12 would be ideally to keep you in good position. And as we see, today, education is mostly spread through lectures, videos or courses online. Fortunately we have tons of programs or companies with huge stack of video content that put you in position to master something in days maybe in hours (think for iTunes University, Coursera, Khan Academy or many many others).

[caption id=”” align=”aligncenter” width=”300”] Fast time[/caption]

In this short post I am going to write for two techniques I am trying to master to do things faster.

Fast reading

When I found this technique I was too happy. First I thought it would be easy to master but I find harder everyday because of read culture I built in years. Main idea is to “turn-off” some behaviors we all have while reading like repeating words. We all read with an average of 150 WPM (word per minute, a unit measure of speed reading) but using this technique and all tricks around could much much higher (found that some famous people were ok with one book in night with more than 600 WPM, would be crazy to do that).

Here are some good links and resources on speed reading:

Wikipedia page : http://en.wikipedia.org/wiki/Speed_reading
Free speed reading course : http://www.youtube.com/watch?v=RmQiOEC8UnM
...and an application to exercise : http://www.spreeder.com/app.php?intro=1

Fast watching

[caption id=”” align=”aligncenter” width=”275”] Fast time[/caption]

I used to watch a lot of videos - courses and thought I was losing too much time (even I was learning, but it’s ego to catch more in shorter period). Tried to find ways to do this process faster, but wasn’t productive. I have to tell that I did this because of need to finish something and start something else and not because of my creativity :D. First, I thought I can watch videos in Fast playback (1.5 faster than normal), I did it and master it fast (huh inception). But, found something interesting in this test, brain could catch even faster transmitted information and I tried with 1.6 … 1.7… and reached 2.0 (because almost all players have no more speed to play videos faster, and it’s not clear anymore after this). And now I’m happy I can watch a 4 hours course in 2, 2 in 1 and so on. But I see I am tired more and faster and I need to be very concentrated while practicing this technique. And a small bug on this :D can’t adopt myself with normal playback speed :(. But I’m fighting this. And I drink a lot of water :D. Maybe brain use all processors on that state and needs more cooler to work :D!

What about your techniques to survive living in a very-fast-time? Comment it.

SOA applications tech stack

2013-09-28T23:54:00+00:00

There are a lot of times when I am asked to complete a stack of technologies for building a Service Oriented Applications. And of course, like for everything, also for this topic there are a lot of answers (and opinions). Using this post I want to express my opinion based in my experience (through years in building medium-to-large applications for public and private sector), what are pieces to combine a SOA lego. So, here I am going to explain what are technologies that could be used to build a SOA application, of course Windows environment friendly. But, this post, is not attempting to give a complete tech stack for this type of apps.

[caption id=”” align=”aligncenter” width=”423”] SOA [/caption]

Always I have tried to see this problem from a very generic standpoint (just three parts). And, separating it in three parts, data part, service part and client part, make it easy to explain and catch.

[caption id=”attachment_461” align=”aligncenter” width=”640”] SOA Tech Stack[/caption]

So, I will refer to this picture to explain what are technologies I used through years to build a robust SOA application.

Data part

As it’s known every application needs a persistent data storage. In this part to make a selection depends in scenario, but first you have to decide in concept level, do you need a structured data store or a non-structured one. In first part immediately take place (famous) RDBMS, with a lot of choices like SQL Server, Oracle or MySQL, or many others. And in second part you have two choices, a file approach (XML, or other type) or a kind-of-db approach, non-structured databases (or NO-SQL).

Service part

In service part, I used to work with different technologies, and I was happy with them, almost happy :). But today it’s a kind of more approach and “developer-culture” what are you going to use, a SOAP approach or REST approach (that’s make you look cool). If you need / choose SOAP approach Windows Communication Foundation has it’s dedicated throne, it’s simply near-to-perfect solution (without configuration part :(, that’s more tricky than hard). And in REST part (that’s TBH I’m preferring and using a lot lately) I prefer two very “fancy” and robust technologies like ASP.Net Web API and ServiceStack.Net. Both of them are easy to start and offer complete functionality list to expose a good REST service.

Client part

Huh, this is a hot part. Tons of choices. First of first, depends on your scenario (hah, I like this approach, do all the post just using “depends on your scenario” :) ), if you need a desktop application, web one or mobile. In Windows desktop app you have two very mature technologies like Windows Forms and Windows Presentation Foundation. I like both, but I prefer more WPF because of it’s declarative user interface technology - XAML. In web part you have two “hard-competitors” ASP.Net and PHP. Now it’s visible that .Net fans always think for ASP.Net and others PHP. In my eyes I see them in pretty same position with a decision indicated by hosting environment. And of course if you need to touch planet you have to think for mobile and again, depends on you scenario you can develop your app for Windows Phone, Android or iOS. All shines on something, user base, money or fanciness or all :).

And, last but not least, something is very clear, Service Oriented Applications are need, style and hot topic nowadays, because of many factors like portability, security, scale-ability, reach-ability and *ability, and you as developer have to master it. Or, your ideas are cloud!?

Try not to become a success

2013-09-14T10:26:00+00:00

Try not to become a man of success, but rather try to become a man of value. A.A.

There's a goal change, dimension change, strategy change, and life change if you follow something valuable. #me

Scards & ICT Creativity of The Year

2013-05-03T11:06:00+00:00

Second part of April was great time for me :D. I justified (somehow) my absence in blogging for long time without new post.

[caption id=”” align=”aligncenter” width=”576”] Scards product[/caption]

On 18th of April we inaugurated Scards, a project I’m involved for a year. Great products, great system. I really encourage to check it out.

[caption id=”” align=”aligncenter” width=”384”] ICT Creativity of the Year[/caption]

Another great happening was on 26th of April, in Tirana, Albania. ICTS Media supported by several other respected institutions (and governments of Albania and Kosovo) organized Albanian ICT Awards, “The highest individual recognition” for contribution and achievement in technology for pas year.

I was very honored and lucky to be the winner of this award for what I’m really happy! I am really happy also for the project (for what I was estimated), Scards that made the difference and I hope will do also in the future.

So in this short post I just want to post some photos of the event I really enjoyed.

[caption id=”” align=”aligncenter” width=”576”] ICT Creativity of the Year[/caption]

Please find some posts about event:

- Top Channel : http://www.top-channel.tv/artikull.php?id=256029
- PC World : http://www.pcworld.al/mbyllet-me-sukses-albanian-ict-awards-2012/

Thank you!

ALNUG & ALSSUG takimi i dytë

2013-02-10T00:57:00+00:00

Sot në ambientet e Innovation Centre Kosovo dy grupet e përdoruesve të teknologjive të Microsoft, Abanian .Net User Group dhe Albanian SQL Server User Group organizuan takimin e dytë me radhë, të përbashkët.

Takimi u hap nga Dukagjin Maloku, Microsoft SQL Server MVP dhe lider i ALSSUG dhe Betim Drenica, lider i ALNUG të cilët folën për organizimin, falenderuan sponsorët dhe kërkuan angazhim më të gjerë të vullnetarëve për folës në tema të ndryshme në të ardhmen.

Sesioni i parë ishte ai i Betim Drenicës (@betimdrenica) i cili foli për “Web Services: Dje - Sot”, duke prekur pak aspektin biznesor të përdorimit të web api-s më herët dhe në ditët e sotme, për të vazhduar më tej me një shpjegim më të gjerë për teknologjinë e ueb shërbimeve dhe standardin HTTP 1.1 dhe për ta mbyllur me shembull real të implementimit të një ueb shërbimi. Prezantimin mund ta shkarkoni nga SlideShare.

Sesioni i dytë ishte ai i Egzon Zenelit (@egzonzeneli) i cili foli për “Window Functions in SQL Server 2012”. Me një informacion gjeneral se çfarë janë dhe ku e si mund të përdoren këto funksione, Egzoni mori një mori shembujsh real të përdorimit të funksioneve “window” për ta mbyllur prezantimin e tij me disa përdorime të avancuara në një bazë shënimesh në SQL Server.

Sesioni i tretë ishte ai i Veton Shalës i cili foli për “Programimi asinkron në C# 5.0”. Vetoni së pari foli për konceptin e asinkronisë dhe pastaj tregoj se si ka evoluar C# si gjuhë programuese në implementimin e këtij funksionaliteti.

Nuk duhet harruar pa përmendur që kjo ngjarje u përkrah edhe nga Shoqata e Teknologjisë së Informacionit dhe Komunikimit të Kosovës - STIKK, dhe nga portali Digjitale.Com.

Web API on IIS 8.0 - 405 Method Not Allowed for PUT

2013-02-05T11:46:00+00:00

Lately I’m extensively developing my web services in ASP.Net Web API and generally speaking it’s good framework in supporting HTTP programming (REST “style”), even if it is in it’s early stages and needed more features to be “completed”.

Yesterday I had a very interesting problem when I published new version of my project (btw, I am developing web api in ASP.Net 4.5 and deploy it in Windows Server 2012 and IIS 8).

When I hit my web api with a PUT request (PUT -> api.mydomain.com/profilecontroller/) web server’s response was error 405 (or method not allowed) while in same time my controller supported all types of requests (get, post, put, delete).

I was surprised with this error while just few minutes earlier everything worked perfectly.

I googled for some time and get disappointed with results - no solution found.

Started to think what I did with my web server and I remembered some “not friendly” touches :D in Web Server (IIS) Role configuration, like installing “WebDAV Publishing”.

I immediately uninstalled (unchecked) that “feature (not Windows Feature :D)” in Web Server (IIS) Role and everything started to work like a charm :D.

It was kind of a stupid solution (I have to admit) but finally everything worked fine :D.

Why Windows Phone 8 should succeed?!

2012-08-12T16:42:00+00:00

Like everyone else has an opinion about new comings I also have mine and I want to share my bits why I think Windows Phone 8 should succeed. According to my opinion there are several reasons and conditions why next mobile operating system from Microsoft should make remarkable debut and gain significant percentage and momentum.

The factors that Windows Phone 8 should succeed according to my opinion are:

"Windows Phone 7" factor
SP1 "culture"
"The 8" ecosystem
Devices and functionality

Windows Phone 7 factor It was that “brave” platform that made Microsoft debut in post-iPhone-Android era in mobile “war”. It was just Microsoft who could enter in a market with such aggressive and hard competitors (like Apple and Google), even beside the fact that just some years earlier they ruled that market, but smartphone is not just for smart people anymore, it’s for everyone.

Windows Phone 7 did a remarkable job in introducing people with new vision for a phone that is digitally authentic, without chrome and borders, with a full-living start screen (thanks to live tiles) and many more ~~Metro~~ aka Modern UI interface principles. We all Windows Phone fans are not happy with numbers (market percentage) but in my opinion mission of “7” is already accomplished. We all (not just WP7 fans) remember times when “7” was faster and more productive than all smartz in market (even better than iPhone), and it was beautiful and a good promise for the future. Fast growing market and developer ROI (in ads) were another great areas where “7” shined, without continuing with more and more true facts. In some words it accomplished it’s mission (anyway, always human say it could be better :D).

SP1 “Culture” It’s something unwritten in Microsoft world, but it’s proved as true fact, since we have seen in the past regularly. Microsoft’s software gain real momentum just after service pack 1. FULL STOP. It’s a kind of culture! And, “8” is not a service pack, it’s a major version, but if we see and compare functionality that Microsoft added in the past, this is a kind of real service pack, and people are considering that in this way. It’s not bad, it’s a good fact, because, people start to trust on that platform, start to see as mature and start to consider it as their possible future choice. And I strongly believe that it’ll happen in this way.

“The 8” ecosystem

This fall (autumn) will make a whole “8 ecosystem” debut. We will have desktop, tablet and phone fresh and 8-tified. In some words phone’s success depends on the success of all platform and I think Microsoft is aware of this. And if we see buzz for Windows 8 (as desktop and tablet) we can freely forecast for some big numbers comings (if we think just Windows 7 users to be upgraded in 8). So people will not have true reason to stay in other platforms in phone while their desktop / tablet is Windows 8. They tend to use all products (for different tasks) that shares same concepts, same design principles and same way of working. This is a strong favor for Windows Phone 8.

Devices and functionality

Even in this time we don’t have full list of (new) functionality that Windows Phone 8 will offer, from promotional event and from some leak information we see big improvements. SD card support, NFC, Data sense, speech, wallet, start screen enhancements, data (messages) backup are just few announced on this stage, all of these make Windows Phone 8 really to compete other big smartz in market. And we can’t finish this post without mentioning devices that will be a strong side of phone. They had just few small problems in the past or not something big to mention (if we remind other’s antenna like problems). And with “8” we are waiting for better devices and better integration with OS. So, in a short summary I strongly believe that Windows Phone 8 will be a success. Let’s see it!