How should I build a RESTful API? /Act I. - What is REST?/

To understand what is a RESTful API, first we have to clear what is REST. (this post is far away from a full review of REST, just a quick one to help building a RESTful API, you can find deeper reviews among the references [at the bottom])

REST = REpresentational State Transfer
The elaboration of REST is a part of Roy Fielding's Dissertation

So, what is REST?

Architectural style for distributed hypermedia systems such as World Wide Web

So, REST is an architectural style. Not identical to HTTP, not an API and it's not just one and only for APIs. It is a set of constraints to build a simplified and decoupled system such as Web.

But we want to create an API in REST style, so we'll use the REST constraints to achieve our goal!

Before move on the architectural constraints, first we should take a quick look at the architectural elements.

Architectural elements: (just a minimal representation)

• Data elements

"The key aspect of REST is the state of the data elements, its components communicate by transferring representations of the current or desired state of data elements"

• Resources 
• "Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on"
• Representations 
• "It is something that is sent back and forth between clients and servers"
• "Never send or receive resources, only their representations"
• "Sequence of bytes, HTML document, archive document, image document"
• Part (it can be the entire) of the resource state

 Architectural constraints:

• Uniform interface

Defines the Interface between Client and Server. Simplifies and Decouples the Architecture. Uniform interface has 4 constraints:

• Identification of Resources
• "Resources must have a unique identifier which can be use to retrieve a resource (e.g. URI)"
• Manipulation of Resources through Representations
• "Resources can be updated (or added) by sending representations from the client to the server"
• Self-descriptive messages
• "It means each message contains all the information necessary to complete the task"
• Hypermedia As The Engine Of Application State
• HATEOAS
• "The ability to navigate resources through hyperlinks/hypermedia is the hallmark of REST" 
• Layered system 
• A client cannot rely a direct connection to the end server
• There can be intermediary layers between the client and the end server
• An intermediary can be a load-balancer or proxy...
• Client-Server
• Separation of concerns
• Improves client portability
• Server can be simpler, more scalable
• Stateless
• "each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server"
• Cacheable
• "the data within a response to a request be implicitly or explicitly labeled as cacheable or non-cacheable"
• Code on demand (optional)
• "server can extend the client functionaility by sending back scripts or code"
• The code is the know-how to process the representation of the given resource

Next time we'll move on the discussion of a RESTful API!
 
References:
http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm 
http://blog.restlet.com/tag/rest-api/
http://www.slideshare.net/kjbuckley/doing-rest-right-3385800
http://www.sitepen.com/blog/2010/05/09/resource-oriented-programming/
http://mrbool.com/rest-architectural-elements-and-constraints/29339
http://nirmata.com/2013/10/rest-apis-part-1/
http://exyus.com/articles/rest-the-short-version/

Symfony2 - DataFixtures

Fixtures are used to load a controlled set of data into a database. This data can be used for testing or could be the initial data required for the application to run smoothly (from symfony.com)

So, the DataFixture Bundle is a great way to help initialize your application, e.g. set up an admin user. You can use it all through the development phase continuously, it has an append option. Without the append argument your database will be erased before the fixtures get injected.

If you plan to use this bundle for testing, you can mix it up with the Faker library to create various test data.

When you work on a not so large project it's a good enough bundle to solve your problems. But if the project is a large one and you want to use a more sophisticated way to make fixtures you should use the Alice library! (it has a Bundle for Symfony2 -> AliceBundle)

Alice calls itself an Expressive fixtures generator. It has a lot of handy tools in its toolbox.

You can create fixtures in a config file! Let's see a Static one:

Nelmio\Entity\User:
    user0:
        username: bob
        fullname: Bob
        birthDate: 1980-10-10
        email: bob@example.org
        favoriteNumber: 42
    user1:
        username: alice
        fullname: Alice
        birthDate: 1978-07-12
        email: alice@example.org
        favoriteNumber: 27

Nelmio\Entity\Group:
    group1:
        name: Admins

Take a look at a Fixture Range config:

Nelmio\Entity\User:
    user{1..10}:
        username: bob
        fullname: Bob
        birthDate: 1980-10-10
        email: bob@example.org
        favoriteNumber: 42

The above fixture configuration ends up 10 users, from user1 to user10.

It integrates with the Faker library initially and has a several other helpful features.