REST Api

Rest Api with Symfony

In this Article, I will describe our journey with developing Rest Api. Our Previous Api development articles are listed below:

1. Soap vs Rest

Before developing Api, it is wise to outline your requirements for developing Api.

Our Use Case: Develop a secure and robust Rest Api for helpdesk system, which supports at least json format. Api could be used to serve specific purpose data (like tickets, replies) and develop mobile Apps. It should be easily scalable and customizable for future needs.

here, I will be using PHP with Symfony framework and bundles & libraries like FOSRestBundle, FOSOAuthServerBundle, NelmioApiDocBundle. Even if you don’t want to use PHP you will get a fair idea about REST Api development.

Basics for REST API:

Restful Api should correlate with following standards,

Rest Api should use corresponding HTTP methods for CRUD like operations.

ActionHTTP Method, example routefetch single resource like ticket with json format:GET /ticket/5.jsonfetch collection of resource like ticket with json format:GET /tickets.jsonadd resource like ticket with json format:POST /tickets.jsonedit resource like ticket with json format:PUT /ticket/5.jsondelete resource like ticket with json format:DELETE /ticket/5.json

Also, Response should be returned with suitable HTTP Status codes. wiki

Status CodeInference200Success: Status OK201Success: Resource created400Client Error: Bad Request401Client Error: Unauthorized403Client Error: Forbidden404Client Error: Not found421Client Error: Too Many Request5xxServer Error

More advantages of Rest can be found here.

Let’s Dive into Rest Api with Symfony

While developing Api, don’t reinvent the wheel unless you need to. There is a lot of libraries, open-source work which could speed-up your work.

Symfony community has already created a set of tools (libraries, bundles) to ease the development of HTTP/REST APIs. it have a couple of well-known bundles such as the FOSRestBundle and the NelmioApiDocBundle.

We used FOSRest Bundle for setting up Rest Architecture. find instructions here

Problems that we faced along the way
1. fosrest conflict with sensio/framework-extra-bundle: >=3.0.13

Solution: try using sensio/framework-extra-bundle to 3.0.12 with friendsofsymfony/rest-bundle: 1.8

2. using fosrest without jmsserializer

solution: enable default symfony serializer service

# app/config.yml
framework
  serializer:
    enabled: true

or use custom fos_rest.service.serializer service

3. conflict with non-api routes, like form can only be submitted once error.

solution 1:

disable body listener

# app/config/config.yml 
fos_rest:
  body_listener: false

solution 2:

or enable zone listener

# app/config/config.yml
fos_rest:
  zone:
   - { path: ^/api/* }

Now, configured routes (like given below) can be used like restful URI corresponding to resources.

Example:

# app/routing.yml
api_resource_routes:
type: rest
prefix: /api
resource: "@AcmeApiBundle/Resources/config/routing.yml"

After Succesfully configuring fosrest, Api

1. provides suitable response based on format in request like resource.json, resource.xml

2. accepts request data based Content-Type header.

How to Secure your Api?

fosrest bundle does provide rest architecture for your Api. but you still need to secure your Api.

how API Security layer differs from conventional web security layer?

Conventional web resources like web pages can be protected by Username & Password combination. web resources often follow the stateful strategy in which credentials are stored in HttpSession object, in a databaseSession, cookie or otherwise.

But, API Requests to Server are Stateless. so, API uses different Authentication and Authorization Schemes. Since API Resources can be shared publically. API would need a secure way for Authenticate and Authorize all Request. We came across some prevailing standard and analyzed them for our use case.

Basic Authentication:

In basic authentication, Username/Password are base64 encoded and send as Authorization header. Read more

Example Request:

Authorization: Basic QPxhoNejpvcGVuIHNlc2FtZQ==

what’s we found out:
Compromise of Secret Token can compromise Username and password.
There is no expiration time for Secret Token.

Api Key:

Api Key is a unique long string (128-bit) assigned to user. It is used for quite similar functions as username/password, allowing access to specific resources. Many Api Providers has opted to use Api Key in Security layer like early Google Api.

Example Request:

curl -v -H "apikey: {api_key_goes_here}" http://{org-name}.uvdesk.com/api/resource

What’s we found out:
Api key is a good way to secure API for specific use. however, Api key becomes troublesome when scaling API to encompass third party apps and extending use beyond what they were originally intended for. so, API Keys Are Not a Complete Solution.

Others

After going through other standards like, HMAC which involves signing the message by access key and OAuth i.e. open standard for authorization. We decided to use Oauth2.0 for securing our Api.

Why we choose OAuth2?

Apart from the fact that google, facebook, twitter, Microsoft and others are shifting to OAuth2 from other standards.i would list some facts why OAuth2 is correct choice:

• OAuth2 is the newer version for OAuth Protocol. it’s simpler than OAuth1.
• It uses Access token with a limited lifetime to authorize the request. so, exploit window is quite small and more secure in Oauth2 due to the use of access tokens.
• In fact, google, facebook, twitter, Microsoft(in azure) supports Oauth2 Api as recommended authentication mechanism. also, they have customized Api for their specific use case.
• Both Two-legged (simple one) or Three legged(complex one) flow can be used for security based on your requirements.

What’s More?

We are just beginning to explore REST Api. we have to lot discuss from how to use OAuth2, generating Docs using NelmioApiDoc, RateLimiting Api to viability and use of HATEOS.