Select Page

Startup VLog – Week 1

As promised last week, I am publishing the first week 1 roundup of my vlog. As I started off my initial focus was on product planning, market analysis, architecture, road map discussions etc. All of this was blown away very soon by the nuts and bolts of running a small organization with zero support. I ran headlong into red tape in registering the company which took a few days to get sorted out. I had to understand terms like Memorandum of Association (MOA), Article of Association (AOA) and many others. Post this was bank work and some more legal documentation.

No sooner did I enjoy a small sense of achievement when I again ran into a wall with infrastructure issues. The company supplying laptops and other hardware frequently changed the cost price and shipping dates. I had to tell my new team members to join a week later due to this. This was something that I have experienced multiple times with multiple vendors during the last couple of weeks. I changed suppliers quickly through folks I knew.Thankfully the new supplier was prompt and we were back on track. With Bangalore’s sweltering heat and power issues, we also had to spend on Air conditioning and power equipment. I am keeping watch on finances as there have been large ticket expenses on infrastructure and now have a climbing burn rate with the 3 new team members who joined us last week.

In the video below, I primarily talk about the small things that took up a bulk of my time and energy as I start off. I would love to talk more about the product, building the team , community participation, the startup eco system in Bangalore and about incubation centers but that’s for another day. Join in on the discussion below. I would love to hear your thoughts.

Video logging my startup journey.

Some of the folks who know me closely know that I recently quit my job at Dell and have started to work on building out my startup. Like any new-born it requires a lot of TLC and takes a lot of my time and energy but it is very exhilarating to start off on a fresh new canvas.

It has been a huge decision to leave a well-paying , stable and long-term association with Dell and invest Money, time and energy into starting out from scratch. As people have come to grips with my decision , I have been fortunate to receive lots of support and encouragement from my colleagues and friends. As I pick my way across this intriguing path, I am planning to video log every week so that I can share it with folks across and also create a self-reference for me to check back on.

Folks always feel that a building a startup is cool and fun but I know that the odds of being a successful startup is less that 1%. However I am in good company and am learning fast. Paul Graham ( founder of yCombinator), one of my biggest inspirations has a post about being relentlessly resourceful and that sort of sums up what I am focussing on every day of this journey. Join in on the discussions and chime in with your thoughts.

 

Identifying Resources and URI design.

Identifying Resources and URI design.

Identifying Resources

The key parts of a Resource oriented architecture are resources, identifiers, representations and the links between them.Designing a RESTful system starts with identifying resources. Resource identification is generally the most flexible aspect of designing a REST based system. There is no exact science to identifying resources and there is no right or wrong with resources identified. We can generally  identify resources from domain nouns. A resource could be a document, a video, a business process or even a device. A resource is any entity that can be uniquely identified and manipulated. Other factors such as resource granularity , resource composition also play a key role in identifying resources.

Resources thus identified can be classified as documents, collections, and controllers. A document resource is a singular concept and is the base for all the other types of resource classifiers. Examples of document resource types are

http://api.onlinestore.com/customer/1234
http://api.onlinestore.com/order/o3576

A collection is a server managed set of resources. Clients can request addition, removal and modification of resources in the collection. The server can accept or deny such requests based on the domain/server logic employed. The collection also defines the identifiers for each resource in the collection. A collection resource can be used to retrieve a paginated list of contained resources. It can also be used to search and retrieve a filtered list of resources. A collection resource can be used as a factory to create member resources and perform bulk operations on them. Examples of collection resources are

http://api.ordermangement.com/orders
http://api.customermanagement.com/customers

A controller models a processing function or a procedural concept as a resource. Controllers provide separation of concern between the client and the server and allows the server to perform atomic operations. A controller is used to perform Domain specific actions that cannot be mapped to the standard CRUD operations. Examples of a controller resource types are

http://api.ordermangement.com/customer/1234/semdmail
http://api.customermanagement.com/pricingengine/order/o3576/calculateprice

Every resource thus identified exposes the same interface and works the same way. To get the value of a resource you send a GET request to that resource’s URI. To delete the resource you call Delete on the resource URI. The standard HTTP verbs described in  Rest – Communicating with Verbs and status codes suffice for all interactions with these resources without the need to invent a new vocabulary.

Designing Identifiers

REST uses URI to identify resources uniquely. URI’s are opaque identifiers. They identify the name and the address of a resource. URI’s ideally should be designed to logically convey the resource model to the client developers. URI’s should enable intuitive identification of resources and every URI designates exactly one resource. This allows each resource to be addressable which is key in a resource oriented architecture. The  generic URI syntax defined by RFC 3986 is below

The authority portion (authority Part) of the URI is used to identify the service owner of the API. The authority part is generally represented by the top level domain and subdomain identifiers of the API service owner.(e.g. http://azure.microsoft.com/api ).The rest of the URI path identifies the API’s resource model. Each forward slash separated path segment within the URI corresponds to a unique resource in the model’s hierarchy. Some URI path segments can be static or variable. The static segments are specified by the API designer while the variable segments have identifiers which are initialized by the client during runtime. URI templates provide a way to parameterize URIs with variables that can be substituted at runtime. The URI Template syntax allows designers to clearly identify and name both the static and variable segments of the URI. A URI template includes variables that must be substituted before resolution.The mark-up in curly braces, {orderId}, provides an indication to client developers to “fill in the gaps” with sensible values. The URI template example below has three variables (customerId, orerId and productId):

http://api.ordermangement.com/customer/{customerId}/orders/{orderId}/products/{productId}

However be warned that when used poorly, URI templates increase coupling between systems and lead to brittle integration.

The query component of a URI contains a set of parameters which corresponds to a variation or derivative of the resource that is hierarchically identified by the path component. The query component can provide clients with additional interaction capabilities such as ad hoc searching and filtering.A URI’s query portion is also a natural fit for supplying search criteria to a collection.A REST API client should use the query component to paginate collection and store results with the pageSize and pageStartIndex parameters. For example:  GET /orders?pageSize=10&pageStartIndex=1

Richardson’s Maturity Model

Richardson’s Maturity Model

The Richardson Maturity Model was developed by Leonard Richardson. It specifies a model to grade REST services according to their adherence to the REST constraints.This model identifies three levels of service maturity based on the service’s support for URI’s, HTTP and Hypermedia.The level 0 represents a basic

rmm

Level Zero Services – Level zero services are characterized by services having only one URI and using a single request type mainly POST. The message contains both the operation to be performed and the data needed for that operation. At this level services do not have the concept of representations or resources that are uniquely identifiable. They also do not use the HTTP verbs and status codes for providing rich  interaction between the client and the server. For e.g Most of the WS-* based web services are level zero since they only use the POST request to tranmit the SOAP based message body.This is also called as swamp of POX (plain old XML)model. HTTP constructs are not used to communicate between the client and the server.

Level One Services –  A level one service has many URI’s but uses a single HTTP verb. Level one services expose multiple resources through unique URI’s. However operations on these resources are performed by a using a single HTTP verb primarily POST.For e.g URI tunneling is only at level one in Richardson’s maturity model

Level Two Services – Level two services host representations and resources at uniquely identifiable URI’s and also use the gamut of HTTP verbs for comunicating beween the client and the server. The URI specifies the resource being operated on  and the operation is performed using the standard HTTP verbs GET, POST, PUT, DELETE  etc.It also uses the standard HTTP status codes for responses and adheres to the Idempotency and safety principles of the HTTP verbs.

Level Three Services – Level three services implement the concept of Hypermedia as the engine of application state ( HATEOAS).Representations hosted at unique URI’s contain URI links to other representations that may be of interest to the client or indicate a choice of actions that can be performed by the client.These choice of actions lead the client through the application resources causing state transtions to occur based on the action chosen by the clinet.

Services that are at Level three are truly RESTful and adhere to the REST principles as defined by Roy Fielding in his thesis.

REST architectural constraints

REST architectural constraints

 

The above constraints describe what a truly RESTful API sould look like.