Thursday, July 25, 2013

REST API Design Rules

Found REST API Design Rulebook to be a useful guideline in designing REST APIs, and it's short n sweet with only 144 pages.



It has dished out a set of clear rules that are practical and easy to follow. Here is a summarized list of all the rules given in the book.

Identifier Design with URIs

URI Format
Rule: Forward slash separator (/) must be used to indicate a hierarchical relationship
Rule: A trailing forward slash (/) should not be included in URIs
Rule: Hyphens (-) should be used to improve the readability of URIs
Rule: Underscores (_) should not be used in URIs
Rule: Lowercase letters should be preferred in URI paths
Rule: File extensions should not be included in URIs

URI Authority Design
Rule: Consistent subdomain names should be used for your APIs
Rule: Consistent subdomain names should be used for your client developer portal

URI Path Design
Rule: A singular noun should be used for document names
Rule: A plural noun should be used for collection names
Rule: A plural noun should be used for store names
Rule: A verb or verb phrase should be used for controller names
Rule: Variable path segments may be substituted with identity-based values
Rule: CRUD function names should not be used in URIs

URI Query Design
Rule: The query component of a URI may be used to filter collections or stores
Rule: The query component of a URI should be used to paginate collection or store results

Interaction Design with HTTP

Request Methods
Rule: GET and POST must not be used to tunnel other request methods
Rule: GET must be used to retrieve a representation of a resource
Rule: HEAD should be used to retrieve response headers
Rule: PUT must be used to both insert and update a stored resource
Rule: PUT must be used to update mutable resources
Rule: POST must be used to create a new resource in a collection
Rule: POST must be used to execute controllers
Rule: DELETE must be used to remove a resource from its parent
Rule: OPTIONS should be used to retrieve metadata that describes a resource’s available interactions

Response Status Codes
Rule: 200 (“OK”) should be used to indicate nonspecific success
Rule: 200 (“OK”) must not be used to communicate errors in the response body
Rule: 201 (“Created”) must be used to indicate successful resource creation
Rule: 202 (“Accepted”) must be used to indicate successful start of an asynchronous action
Rule: 204 (“No Content”) should be used when the response body is intentionally empty
Rule: 301 (“Moved Permanently”) should be used to relocate resources
Rule: 302 (“Found”) should not be used
Rule: 303 (“See Other”) should be used to refer the client to a different URI
Rule: 304 (“Not Modified”) should be used to preserve bandwidth
Rule: 307 (“Temporary Redirect”) should be used to tell clients to resubmit the request to another URI
Rule: 400 (“Bad Request”) may be used to indicate nonspecific failure
Rule: 401 (“Unauthorized”) must be used when there is a problem with the client’s credentials
Rule: 403 (“Forbidden”) should be used to forbid access regardless of authorization state
Rule: 404 (“Not Found”) must be used when a client’s URI cannot be mapped to a resource
Rule: 405 (“Method Not Allowed”) must be used when the HTTP method is not supported
Rule: 406 (“Not Acceptable”) must be used when the requested media type cannot be served
Rule: 409 (“Conflict”) should be used to indicate a violation of resource state
Rule: 412 (“Precondition Failed”) should be used to support conditional operations
Rule: 415 (“Unsupported Media Type”) must be used when the media type of a request’s payload cannot be processed
Rule: 500 (“Internal Server Error”) should be used to indicate API malfunction

Metadata Design

HTTP Headers
Rule: Content-Type must be used
Rule: Content-Length should be used
Rule: Last-Modified should be used in responses
Rule: ETag should be used in responses
Rule: Stores must support conditional PUT requests
Rule: Location must be used to specify the URI of a newly created resource
Rule: Cache-Control, Expires, and Date response headers should be used to encourage caching
Rule: Cache-Control, Expires, and Pragma response headers may be used to discourage caching
Rule: Caching should be encouraged
Rule: Expiration caching headers should be used with 200 (“OK”) responses
Rule: Expiration caching headers may optionally be used with 3xx and 4xx responses
Rule: Custom HTTP headers must not be used to change the behavior of HTTP methods

Media Type Design
Rule: Application-specific media types should be used
Rule: Media type negotiation should be supported when multiple representations are available
Rule: Media type selection using a query parameter may be supported

Representation Design

Message Body Format
Rule: JSON should be supported for resource representation
Rule: JSON must be well-formed
Rule: XML and other formats may optionally be used for resource representation
Rule: Additional envelopes must not be created

Hypermedia Representation
Rule: A consistent form should be used to represent links
Rule: A consistent form should be used to represent link relations
Rule: A consistent form should be used to advertise links
Rule: A self link should be included in response message body representations
Rule: Minimize the number of advertised “entry point” API URIs
Rule: Links should be used to advertise a resource’s available actions in a state-sensitive manner

Media Type Representation
Rule: A consistent form should be used to represent media type formats
Rule: A consistent form should be used to represent media type schemas

Error Representation
Rule: A consistent form should be used to represent errors
Rule: A consistent form should be used to represent error responses
Rule: Consistent error types should be used for common error conditions

Client Concerns

Versioning
Rule: New URIs should be used to introduce new concepts
Rule: Schemas should be used to manage representational form versions
Rule: Entity tags should be used to manage representational state versions

Security
Rule: OAuth may be used to protect resources
Rule: API management solutions may be used to protect resources

Response Representation Composition
Rule: The query component of a URI should be used to support partial responses
Rule: The query component of a URI should be used to embed linked resources

JavaScript Clients
Rule: JSONP should be supported to provide multi-origin read access from JavaScript
Rule: CORS should be supported to provide multi-origin read/write access from JavaScript

Tuesday, July 16, 2013

Fuse ESB Demo Code

Fuse ESB Enterprise documentation is making use of demonstration code to illustrate the capabilities of the system. Explanations are not very clear to follow without the code, but unfortunately the code is for subscribers only.

Downloading the demonstration package

The source code for the demonstrations is packaged as a Zip file, cxf-webinars-assembly-1.1.1-src.zip, and is available from the following location:
http://repo.fusesource.com/nexus/content/repositories/subscriber/org/fusesource/sparks/fuse-
webinars/cxf-webinars-assembly/1.1.1

When you try to navigate to this location with your browser, you will be prompted for a username and password. Enter your subscription login credentials to gain access to this directory and click on cxf-webinars-assembly-1.1.1-src.zip to start downloading.

Did a little Googling to see if any generous developer has shared the code, and look what we found!

The actual git repository they use for storing these projects is not restricted.

http://fusesource.com/forge/git/sparks.git/?p=sparks.git;a=tree

It's not possible to clone it, since it requires authentication. But can click on the snapshot  (http://fusesource.com/forge/git/sparks.git/?p=sparks.git;a=snapshot;h=HEAD;sf=tgz) and the entire lot is downloaded.

Wednesday, July 10, 2013

Frequently Used Linux Commands

For my easy reference,

find . -name *.jar | xargs grep -i 'ABC.class'
# Find a jar file which has ABC.class in it

printenv
# Environment variables

printenv | grep proxy
# Environment variables with proxy in name

export https_proxy=http://x.x.x.x:3128
# Set environment variable

sudo su
# Login as super user

rm -rf folderToDelete
# Delete the folder and the contents

netstat -anp|grep :7001
# Find a process binding a port

kill -9 21286
# Kill process

telnet hostA 1521
# Telnet a port

nslookup hostA
# 

uname -a
# kernel-name, nodename, processor, OS etc

lsb_release -a
# OS version

cat /etc/*release 
# OS version

df -h
# file system sizes & free space

du -s folderloc
# folder size

du --si -s file 
# File size shown in G,M

ssh root@serverA
# Connect to serverA as root

scp root@serverA.abc.com:/path/a.log b.log
# Copy a file from serverA

scp -r /path/folderA  userB@serverB:/path/folderB
# Copy a folder to serverB

tar -cf archive.tar foo bar
# Create archive.tar from files foo and bar.

tar -xf archive.tar
# Extract all files from archive.tar.

vpnc-connect
# VPN connect

date
# Current date

date +%T -s "15:22:13"
# Update time

split --bytes=50m largeFile.log splitFile_
# Split a file to files with 50m


Common Options

-f, --force
-r, -R, --recursive
-a, --all
-v, --verbose
--help
--version

SOAP vs REST


SOAP REST
Simple Object Access Protocol REpresentational State Transfer
XML based messaging protocol Architectural style
JAX-WS JAX-RS
XML JSON, XML, plain text etc
RPC URL path
Binary data that is sent must be encoded Binary data can simply be delivered
Standard specification No standard specification
Exposes operations that represent logic Exposes resources that represent data

Install Soap UI on Ubuntu

It should be as simple as this

sudo add-apt-repository ppa:upubuntu-com/web
sudo apt-get update
sudo apt-get install soapui

But since I'm behind a proxy "add-apt-repository" gives an error.

Traceback (most recent call last):
File "/usr/bin/add-apt-repository", line 125, in 
ppa_info = get_ppa_info_from_lp(user, ppa_name)
File "/usr/lib/python2.7/dist-packages/softwareproperties/ppa.py", line 84, in get_ppa_info_from_lp
curl.perform()
pycurl.error: (7, "couldn't connect to host")

Check if proxy is configured as environment variable.

printenv | grep proxy

Both http_proxy and https_proxy should be there. If not add them.

export http_proxy=http://x.x.x.x:port
export https_proxy=http://x.x.x.x:port

Run sudo with the -E option so that environment variables get passed to the root account.

sudo -E add-apt-repository ppa:upubuntu-com/web

Tuesday, July 9, 2013

SyntaxHighlighter in blogger

I can't believe that I wrote a dev blog for a year without using a tool to highlight Syntax.

I added SyntaxHighlighter (http://alexgorbatchev.com/SyntaxHighlighter/) today and am delighted with the result. Followed the tutorial on http://oneqonea.blogspot.com/2012/04/how-do-i-add-syntax-highlighting-to-my.html

You basically have to add the following to the in the blog template.








We can keep only the brushes we need (.js includes) and remove the rest.

There are several themes as mentioned in http://alexgorbatchev.com/SyntaxHighlighter/manual/themes/ and I'm using the eclipse theme.

When creating blog posts surround the code snippets with following tags. Pick the right brush depending on the programming language used.

<pre class="brush:java;"
Code Snippet
</pre>


Camel Route: Quering Oracle DB


camel-context.xml





 
  
   
   
    Select * from ACCOUNT
   
   
   
  
 

 
  
  
  
  
 

 



pom.xml



  
  
   org.apache.camel
   camel-core
   2.10.0.redhat-60024
  

  
   org.apache.camel
   camel-spring
   2.10.0.redhat-60024
  

  
   org.apache.camel
   camel-jdbc
   2.10.0.redhat-60024
  

  
    org.springframework
    spring-jdbc
    3.1.0.RELEASE
   

   
    com.oracle
    ojdbc6
   11.2.0
   

  


Following dependency issued were encountered when implementing the above.

java.lang.ClassNotFoundException: org.springframework.jdbc.datasource.DriverManagerDataSource 

Adding spring-jdbc jar was the solution, but the question was which version.


org.springframework
spring-jdbc
x.x.x


Tried 1.2.9, 2.0.1, 2.5.6. All gave the following error.

[ERROR] Failed to execute goal org.apache.camel:camel-maven-plugin:2.10.0.redhat-60024:run (default-cli) on project poc-database: null: MojoExecutionException: org/springframework/core/env/EnvironmentCapable: org.springframework.core.env.EnvironmentCapable -> [Help 1]
[ERROR] 
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.

Running with -e switch revealed the following error.


Caused by: java.lang.NoClassDefFoundError: org/springframework/core/env/EnvironmentCapable

This class was found in 3.x versions of spring-jdbc. Tried with 3.1.0.RELEASE, and it gave the following error.

[ERROR] Failed to execute goal org.apache.camel:camel-maven-plugin:2.10.0.redhat-60024:run (default-cli) on project poc-database: null: MojoExecutionException: InvocationTargetException: Error creating bean with name 'dataSource' defined in URL [file:/home/kl40306/SAM6/Fuse_POC/workspace/poc-database/src/main/resources/META-INF/spring/DatabaseSample.xml]: Error setting property values; nested exception is org.springframework.beans.NotWritablePropertyException: Invalid property 'driverClass' of bean class [org.springframework.jdbc.datasource.DriverManagerDataSource]: Bean property 'driverClass' is not writable or has an invalid setter method. Does the parameter type of the setter match the return type of the getter? -> [Help 1]
[ERROR]

The reason is the attribute which was "driverClass" is now "driverClassName" in DriverManagerDataSource.

After fixing the above, following error came up.

PropertyAccessException 1: org.springframework.beans.MethodInvocationException: Property 'driverClassName' threw exception; nested exception is java.lang.IllegalStateException: Could not load JDBC driver class [oracle.jdbc.driver.OracleDriver]

Needed to add Oracle maven dependency.


   com.oracle
   ojdbc6
   11.2.0
  

This is not downloaded automatically from maven repositories. Need to install manually.

Download the jar and run

mvn install:install-file -Dfile=/path_to_jar/ojdbc.jar -DgroupId=com.oracle -DartifactId=ojdbc6 -Dversion=11.2.0 -Dpackaging=jar