Our Geek Space

- Every resource is identified by an URI

The URI <base_uri>/car/<car_id> identifies the car whose ID is <car_id>. If you are designing an API to interact with a software system, the ID probably will be the primary key of the car in the database

- Use the HTTP Verbs.

GET <base_uri>/car/<car_id> -> This operation retrieves information about the car whose id is car_id. No side effects here, please!
GET <base_uri>/cars -> Retrieves the set of cars, parameters containing the page_size and page_number are highly recommended. No side effects.
POST <base_uri>/car -> Create a new car, the car attributes are passed as HTTP parameters. This operation must retrieve the ID of the new object created.
PUT <base_uri>/car/<car_id> -> Modify the data associated with the car, the attributes are passed as HTTP parameters
DELETE <base_uri>/car/<car_id> -> You want to delete an object? Just it!

Don’t use action names, like get_car, or browse_for_id in the URI, the verbs indicate the desired action

A principle-design discussion… singular or plural nouns at the URI? Personally I prefer nouns in singular for operations involving ONE resource, and plural for MORE than one resource.

- Use of HTTP Status codes
Use it to indicate the result of the operation.

I recommend that the API return appropriate HTTP status codes for each request.

200 OK: The request has been successfully completed.
304 Not Modified: Operation ok. There was no new data to return
400 Bad Request: The request is invalid. Error messages are returned for explanation purposes.
401 Not Authorized: The credentials provided are invalid or are needed for the operation.
403 Forbidden: The request is refused by the API implementation. Error messages are returned.
404 Not Found: The resource requested doesn’t exist. Ex: The provided car_id in the url doesn’t exist.
500 Internal Server Error: An unrecoverable error has occurred at server side.

502 Bad Gateway: The API service is down or being upgraded

503 Service Unavailable: The service is overloaded with a lot requests and can’t manage the incoming request.

- Error Messages

When the API returns error messages it must comply with a structure. Here I present a simple structure in JSON format:

{
    error_messages: [
        "error_message_1",
        "error_message_2",
        ...,
        "error_message_n"
    ]
}

- Data Format

The operations return information about the resource requested or information about error messages. The format of that information could be preferably at the moment JSON or XML.
If you will be supporting more than one format, or think that in future you’ll be, a possible manner is to include the format at the URI, for example:
PUT <base_uri>/car.json/<car_id>
PUT <base_uri>/car.xml/<car_id>

Conclusion: The key base-aspects of designing a RESTful API are
- Identify every resource (or object in OOP idiom) with an URI
- Use HTTP verbs
- Use HTTP status code
- Don’t use action names in the URI

An important implementation detail: Use UTF-8, unless your data is only on languages with high code points (digging more in the cloud about this topic is recommended)

Another important aspect is about security access to the operation, but is an subject for a future post, stay tuned!

When your business is about pushing and pulling data from an external system, or exposing your application domain to external clients, you often have two options: SOAP Webservices or a RESTful service. If you’re here there are great chances that you are ridding this new hype-age of web2.0 startups as if it was a new religion (just like us). But these preferences are not enough to achieve a successful job done, you must learn new concepts and “stay in the zone”.

Ok, so you need to design a RESTful API (and implement it later?), you must be asking “first what the hell is REST?” “Why you write RESTful?” “Or is it a mistake?”. Here we go. If you feel comfortable with the basic concepts please jump to the second part.

What is REST?

REST (REpresentational State Transfer) is a style or a set of principles for software architecture for distributed systems, nothing else, is not a specification neither a standard and neither an implementation.

Actually REST has a niche in applications over HTTP, but technically this is not a barrier.
- HTTP is a stateless protocol
- It defines a set of operations: POST, GET, PUT, DELETE
- Every resource has an universal address, the URI
- Hypermedia documents for modeling the information of a resource

What is a Resource?

A resource is nothing else than the objects that you expose, like an invoice, a paycheck or a blog entry.

HTTP Verbs:

The POST, GET, PUT and DELETE verbs map with the basic CRUD operations
POST -> Create
GET -> Read
PUT -> Update
DELETE -> Delete

REST Operations

A REST operation consists of:
- an URI identifying the resource
- a set of additional parameters
- a HTTP verb
- the response status code
- the information retrieved by the operation

continues…

brief introduction to this tools …

Moodle (www.moodle.org): Moodle is a Course Management System (CMS), also known as a Learning Management System (LMS) or a Virtual Learning Environment (VLE). It is a Free web application that educators can use to create effective online learning sites

(we recommend moodle for elearning sites … no doubt)

Wiziq(www.wiziq.com): WiZiQ is a free alternative to expensive conferencing tools selling as online teaching/learning software

(very good tool for virtual class)

For this issue try this two solutions:

*First of all try with this information from a wiziq support center…

WiZiQ Live Class form picks up time zone as you set in your profile on Moodle. Please set your time zone in your Moodle profile. All the following steps need to be done in your Moodle account and not in your WiZiQ account.

1. Sign-in to your Moodle account.

2. Visit your profile that you have filled on Moodle. There you have time zone set as GMT +13.

3. Go to ‘Edit Profile’ tab.

4. In the Timezone field select ‘GMT+1’ and save the information.

5. Now, select WiZiQ Live Class as an activity. You should be able to add WiZiQ Live Classes for GMT which I’m assuming is your actual time zone.

**if it does not work, we will have to change the default value of the timezone. To do this … Follow these steps:

1. In the module of wizip “domain/mod/wiziq”, change one line in two files: “mode1.html” and “session.php”
2. find this peace of code:
   default:
   {
   $timezone=”GMT+13″;
   }
3. change for:(for example my timezone is GMT-3)
   default:
   {
   $timezone=”GMT-3″;
   }

enjoy

Today I logged to my facebook and my home was like always.. nothing new… nothing told me that the ownership and proprietary rights had changed, and nobody told me that my personal information now belongs to Mark (including all my beautiful pictures!)
What happened with the “Accept” and “Not accept” buttons? (maybe Mark forgot about this…)

I was thinking about why this happened…
Maybe Mark needs money! How much does the data of the largest social network in the world cost? Surely a lot of money. Imagine if the data belongs to the social network rather than the users themselves.
Maybe Mark has development problems! If a user is deleted from facebook, what happens with all the information linked to his friends? (delete in cascade? )

I don’t know what happens here and I don’t care. Obviously this is annoying because you don’t have control of anything and this change was not clear at all.

This is the paragraph of the controversy:

You hereby grant Facebook an irrevocable, perpetual, non-exclusive, transferable, fully paid, worldwide license (with the right to sublicense) to (a) use, copy, publish, stream, store, retain, publicly perform or display, transmit, scan, reformat, modify, edit, frame, translate, excerpt, adapt, create derivative works and distribute (through multiple tiers), any User Content you (i) Post on or in connection with the Facebook Service or the promotion thereof subject only to your privacy settings or (ii) enable a user to Post, including by offering a Share Link on your website and (b) to use your name, likeness and image for any purpose, including commercial or advertising, each of (a) and (b) on or in connection with the Facebook Service or the promotion thereof

UPDATE 17/02: Facebook has rolled back to it’s previous TOS, surely because of all the negative reactions this caused in the online community. This happens when this type of changes, which are inherently controversial, are poorly communicated and explained AFTER being implemented. This is a sensitive issue, and before I am stripped apart of the ownership of MY data I would like to be at least told about it. (source: http://www.techcrunch.com/2009/02/17/facebook-backtracks-under-community-pressure-goes-back-to-old-tos-for-now/)

Many people think that configuring a mail server is a trivial task … you think the same? don’t be so sure…
I remember my thoughts… “I want to inbox !! why are the mails arriving to the junk folder?? I’m not a spammer”

The truth regarding this, is that we do not have a unique technique or way to inbox in the different mail servers (hotmail, yahoo, gmail, aol, etc), because these mail servers have different security protocols (SPF, Domain Keys, Sender ID?…) and each has it’s particular tricks.

The first step is to make sure that  all the DNS stuff is configured properly. Some mail servers can send mail from multiple IP addresses at the same time, so, you must determine the IP or IPs that you want to use to send emails.  Once you have identified this IPs, you must view their rDNS configuration (Reverse DNS) .  You can do this executing the following command:

host -t PTR 206.189.123.25

After executing the command you will look at somthing like this:    25.123.189.206.in-addr.arpa domain name pointer anyplace.pepetrueno.com.

The sentence in bold above must point to the mail server! (Obviously the first time it will point to some place that you don’t know, commonly a temporary hosting domain. Every mail server has a name (machine name) and the rDNS must point to that name. (xeonmachine02.myhostingprovider.com for example)
To configure the rDNS in a correct way, you must submit a ticket to the hosting that manages your server (the IP owner) and ask for this change.
Once this change is done, you must wait 12-24-48 hours (propagation time) and test again.

The rDNS setting is a very important thing, almost all mail servers have this validation. For example, if this configuration is wrong when you are trying to send mails to hotmail,  your mail is discarded and doesn’t even go to junk folder.

How to inbox in hotmail?

To inbox in hotmail, you must implement the SPF validation(more details). The truth is that hotmail, has a security framework called Sender ID that is based in SPF and the configuration is the “same” (Sender ID has other features that you can use).
The first step is create a SPF record and with this wizard it is really easy.

The SPF record is a string line like this:  v=spf1 ip4:128.121.145.168 mx mx:one.textdrive.com include:cmail1.com include:aspmx.googlemail.com a ~all  (Twitter SPF configuration)

Basically in the record you have to specify wich IP or IPs can send emails using your domain.

Once you have your SPF record, you must publish this record in your DNS server. If you use a DNS server provided by Godaddy.com for example (or another hosting/server provider), you will have a tool inside your console that lets you enter your SPF record. Anyway, if you don’t find the tool, submit a ticket to your provider!
If you have a DNS server, you must put the SPF record inside the configuration file of your domain. (mydomain.com.db for example).  (If you have a DNS server, I’m sure that you know what I mean.)
In this configuration file you must add a line like this:  mydomain.com IN TXT ” v=spf1 ip4:128.121.145.168 mx mx:one.textdrive.com include:cmail1.com include:aspmx.googlemail.com a ~all”… that’s it.

To test if your SPF record is published, you can go the wizard that I use above and put your domain name. In the step 2, if you have a SPF record, the wizard will display it to you.
Another way to test your SPF record, is use this tool that I found .. it’s really good.

How to inbox in yahoo?

To inbox in yahoo you must configure Domain Keys. I will write about this configuration (or maybe my friend Gian) in a few days.

I hope this helps you with your problems

So you want to build your own social network site on rails? As you probably know, there are many plugins around to add social functionality to your site, and there are also some open source platforms that provide you with complete social network functionality. Some of them are Lovd by Less, comunity engine, tog, etc. These platforms, as rails premises, are based in the idea of not reinventing the wheel. In this post we’ll be referring about tog our experience installing it and trying it out.

Why are we using tog? Actually we are not using it, we are just doing a proof of concept trying out the different platforms and getting to know each of them. The idea behind this is to have enough knowledge to, according to our clients requirements, select the best solution for them and for us in order to save our clients some money by reducing our development time.

What is tog? Tog is a non-intrusive, extensible open source platform that helps you to add social network features to your Ruby on Rails apps. We aim to convert the tedious and long process of creating a community site on a straightforward process that will give your site social capabilities in minutes. (from www.toghq.com/)

Installing tog may not be a simple procedure for a Rails beginner, but the install process is very well explained in their wiki. After following the procedure you will have installed a very complete and expandable social network. It is composed by many plugins developed by tog and some by 3rd parties. After installing the basic plugins you can install more plugins that will easily adapt to the default site.

Tog is today in version 0.4, which means you will probably find some bugs and things to fix. Here are some we ran into:

1. After running the togify command the following error may appear: “error  There has been a problem trying to unpack the tog_core tarball downloaded from github. Remove the changes made on your app by togify and try again. Sorry for the inconveniences. We found the solution in the project assembla here
2. In the migration create_posts from plugin tog_conversation the line t.datetime :published_at is missing

Another thing you shouldn’t forget is to set up your email conf, since some plugins may depend on the user activation like the message ones (I tried to manually activate some users, and then had to manually fix some things than an observer was supposed to do after activation)

The greatest thing about tog is the ease of extending it. You can read about it here. Basically you can override any behavior you want just by creating models, controllers or views like you would normally do in your apps. On the cons side, it may be a bit complex finding out what functionality is where, to override with your own. The idea is to not touch the plugins and use new controllers, models, etc to extend. This will allow plugins to be updated when they need to, without affecting your site’s working functionality.

In conclusion, I think tog is a very promising platform that may be a great solution for building social networks on the go, allowing us to extend them to meet our needs. This may be a good solution for a user who just wants his site running. If you want to customize too much about it, you should consider other platform or starting from scratch.

We are right now working on adding Facebook Connect to a demo site we are building with tog, please come back to know how that went