What are RESTful web services:
REST is an architectural style which provides direction for building distributed ans loosely coupled systems.REST is not linked to any particular platform or its an idea to develop services to function similar to the web.
REST is nothing but REpresentational State Transfer.It describes how one system can communicate with another over web.We can compare REST services as methods in our programme,in order achieve certain tasks in our programme we are calling some methods from our programme,in the same way we are creating REST web services.I would rather say REST web services and methods on web that can be consumed by calle(clients like browser,mobile apps or other consumers.).So two systems can comminucate over web with the help REST web services so there must by some data that will be exchanged between two parties.That data should be having some state at particular instance and has some form of representaion,so this is nothing but REpresentation state transfer.For example,we have an emplopyee object having id,name and address as attributes.So curently that object has id=1,name='xyz' and address='India' as current state and we pass it as JSON.So this is what as REpresentaional state transfer.
Most people think that REST is HTTP but REST is not HTTP because in its most general form REST exists to assist the concept of verb against an arbitary collection of nouns.
One most important point is what is the difference between website and a web service.A website is consumed by humans whereas web services are consumed by programmed clients.
REST web services rests on three mail things and those are Resources,Representation and Verbs.URL in web services is a sentence where resources are nouns and verbs are HTTP methods.
Resources:Resources are the endpoints of API.They may be business entities like student,employee and so on.While working on rest web services ,the first task is to identify resources and how they link with each other.
Representation: Representation is nothing but a way to showcase resources to clients.REST supports most of the representation formats including but not limited to json,xml.
Verbs:Verbs decides what actions to perform an given resource.Verbs can be GET,PUT,POST and DELETE etc.
Guidelines for designing REST web services:
1)API Endpoint:
Lets say we have resource as employee and we need to write REST API's for that,so we can start as:
employee/createEmploye
employee/deleteEmployee
employee/updateEmployee
employee/createEmployee
This will results in tons of API's and it can duplicate the code and increases maintance cost associated with the API's.So what's wrong with the above way to create API's.URL should only contain resources and not verbs,let the HTTP Verbs do the job and do not include those verbs in URL.
So the API endpoints should look like,
URL : employee/ HTTP verb:POST will create employee resource
URL: employee/{id} HTTP verb:GET will get employee specified by id
URL: employee/{id} HTTP verb:DELETE will delete employee specified by id
URL:employee/{id} HTTP verb:PUT will update employee specified by id
Now lets say we have resources under resource like we have employee under department we can have,
URL : department/{id}/employee HTTP verb:POST create employee under department specified by id
URL: department/{deptId}/employee/ HTTP verb:GET get all employee under department specified by deptId
URL: department/{deptId}/employee/{empId} HTTP verb:GET get employee with id empId under department specified by deptId
URL: department/{deptId}/employee/{empId} HTTP DELETE delete employee with id empId under department specified by deptId
2)HTTP methods:
1.GET : retrieve an existing resource.
2.POST : Create new entry for resource.POST is non idempotent method which means every time a request is made it has different effect.
3.PUT : Modify an existing resource.PUT is idempotent method which means every time request is made it has same effect.
4.DELETE : Delete an existing resource.
3)HTTP response codes:
Whenever a request is made to server it must return some response either failed or success,so that client can aware of it.For successful operation it should return 2xx series status codes.For client request error 4xx series status codes and for server side error 5xx status codes should be return
4)Versioning:
Versioning should be considered when the servers are unable to maintain the compatibility.Versioning is done if some clients wants different behaviuor than others.Versioning can be accomplish using version number in URL or it can be achieved using accept and content type with version numbers instead of specifying in the URL.
Lets say we have Order as resource and we need to create two versions of this resource where in one API order resource should not include items within it which is V1 and other API which includes items within the order then we can have,
Example of version number in URL:
v1/order/{id} HTTP verb:GET get order specified by id(does not include items in order)
v2/order/{id} HTTP verb:GET get order specified by id(include items in order)
Example of version number in header:
order/{id} Accept:application/json;version=1 get order specified by id(does not include items in order)
order/{id} Accept:application/json;version=2 get order specified by id(include items in order)
These are my own opinions on designing RESTful web services,your views are also welcome.
REST is an architectural style which provides direction for building distributed ans loosely coupled systems.REST is not linked to any particular platform or its an idea to develop services to function similar to the web.
REST is nothing but REpresentational State Transfer.It describes how one system can communicate with another over web.We can compare REST services as methods in our programme,in order achieve certain tasks in our programme we are calling some methods from our programme,in the same way we are creating REST web services.I would rather say REST web services and methods on web that can be consumed by calle(clients like browser,mobile apps or other consumers.).So two systems can comminucate over web with the help REST web services so there must by some data that will be exchanged between two parties.That data should be having some state at particular instance and has some form of representaion,so this is nothing but REpresentation state transfer.For example,we have an emplopyee object having id,name and address as attributes.So curently that object has id=1,name='xyz' and address='India' as current state and we pass it as JSON.So this is what as REpresentaional state transfer.
Most people think that REST is HTTP but REST is not HTTP because in its most general form REST exists to assist the concept of verb against an arbitary collection of nouns.
One most important point is what is the difference between website and a web service.A website is consumed by humans whereas web services are consumed by programmed clients.
REST web services rests on three mail things and those are Resources,Representation and Verbs.URL in web services is a sentence where resources are nouns and verbs are HTTP methods.
Resources:Resources are the endpoints of API.They may be business entities like student,employee and so on.While working on rest web services ,the first task is to identify resources and how they link with each other.
Representation: Representation is nothing but a way to showcase resources to clients.REST supports most of the representation formats including but not limited to json,xml.
Verbs:Verbs decides what actions to perform an given resource.Verbs can be GET,PUT,POST and DELETE etc.
Guidelines for designing REST web services:
1)API Endpoint:
Lets say we have resource as employee and we need to write REST API's for that,so we can start as:
employee/createEmploye
employee/deleteEmployee
employee/updateEmployee
employee/createEmployee
This will results in tons of API's and it can duplicate the code and increases maintance cost associated with the API's.So what's wrong with the above way to create API's.URL should only contain resources and not verbs,let the HTTP Verbs do the job and do not include those verbs in URL.
So the API endpoints should look like,
URL : employee/ HTTP verb:POST will create employee resource
URL: employee/{id} HTTP verb:GET will get employee specified by id
URL: employee/{id} HTTP verb:DELETE will delete employee specified by id
URL:employee/{id} HTTP verb:PUT will update employee specified by id
Now lets say we have resources under resource like we have employee under department we can have,
URL : department/{id}/employee HTTP verb:POST create employee under department specified by id
URL: department/{deptId}/employee/ HTTP verb:GET get all employee under department specified by deptId
URL: department/{deptId}/employee/{empId} HTTP verb:GET get employee with id empId under department specified by deptId
URL: department/{deptId}/employee/{empId} HTTP DELETE delete employee with id empId under department specified by deptId
2)HTTP methods:
1.GET : retrieve an existing resource.
2.POST : Create new entry for resource.POST is non idempotent method which means every time a request is made it has different effect.
3.PUT : Modify an existing resource.PUT is idempotent method which means every time request is made it has same effect.
4.DELETE : Delete an existing resource.
3)HTTP response codes:
Whenever a request is made to server it must return some response either failed or success,so that client can aware of it.For successful operation it should return 2xx series status codes.For client request error 4xx series status codes and for server side error 5xx status codes should be return
4)Versioning:
Versioning should be considered when the servers are unable to maintain the compatibility.Versioning is done if some clients wants different behaviuor than others.Versioning can be accomplish using version number in URL or it can be achieved using accept and content type with version numbers instead of specifying in the URL.
Lets say we have Order as resource and we need to create two versions of this resource where in one API order resource should not include items within it which is V1 and other API which includes items within the order then we can have,
Example of version number in URL:
v1/order/{id} HTTP verb:GET get order specified by id(does not include items in order)
v2/order/{id} HTTP verb:GET get order specified by id(include items in order)
Example of version number in header:
order/{id} Accept:application/json;version=1 get order specified by id(does not include items in order)
order/{id} Accept:application/json;version=2 get order specified by id(include items in order)
These are my own opinions on designing RESTful web services,your views are also welcome.
Comments
Post a Comment