Important aspects of the RESTful API for your project
This article has long been brewing in my head, but in a completely different format.
After reading the last few clumsy articles on the topic of WEB-services (for example: http://habrahabr.ru/blogs/development/108973/ ) and using REST technology in them, I decided that it was time to throw off the laziness, set aside time and write “ reformatted "in my head article.
So, briefly, what you will find in the article and to whom it will be useful:
- beginners who are interested in or plan to write a web service for the project
- pros are unlikely to find something new for themselves
- the general ideology of REST
- use of CRUD in WEB services
- KISS principles when building routers
- best practics
- a little PR;)
- references, literature
Where to begin to decide you, I recommend first reading the article, then google a little more, have a cup of tea / coffee / necessary_ emphasize, put your thoughts on the shelves and then start creating your hey pi-ah.
What is REST * (1)?
REST is “Representational State Transfer”, in other words, data representation in a format convenient for the client, by the client we mean client software from the client <-> server model.
In turn, web services created using the HTTP protocol and REST principles are called the RESTful web service.
An uninitiated person may immediately ask: why do we need such services? I will give a simple example based on REST and OAuth technologies: you have a gmail account and a dropbox account. Dropbox offers you extra space for each invited friend, but writing a letter manually and sorting through all the addresses from the gmail address book is not just boring, but also time consuming. Dropbox offers “come on, buddy, I will import contacts and send invitations”. It is clear that none of you will want to give your password from the box on the drop box. This is where the “magic” of RESTful web services comes into play. Using the API (hey-pi-ah, not “api”, as many used to say), dropbox makes a request to google web service, then “sends” you to google login page, so you enter your password in the form of google , Google authorizes you and lets you know (gives access_token) to dropbox about the success of the auth-process (authentication). In the end, having a unique token (access_token) and attaching it to each API request, dropbox has the ability to work with your personal data without knowing anything about your password.
It is important to remember that REST is not necessarily the use of the HTTP protocol, although initially the architecture was developed using just HTTP. REST can use any application layer protocol to transport data.
')
When developing RESTful web services, it is important to remember about the CRUD * (2) methodology, which in the decrypted translation means: create-read-edit-delete (create-read-update-delete).
Since the development of web services is carried out using the HTTP protocol, you need to use its buns, namely: use the protocol methods to determine the action on the resource. The following standards are generally accepted in the REST world:
POST - create
GET - read (read, receive)
PUT - update (change, update or create, if it does not exist, it is sometimes used in this version)
DELETE - delete (delete)
It should be noted that the PUT and DELETE methods are difficult to implement, and due to the peculiarities of browsers, these methods are implemented “humanly” by AJAX on the client-browser side, and it also does not seem to work in all browsers. Therefore, it is accepted to use these methods by means of “overloading” the POST method. In other words: You send a reserved variable with the POST method, for example: http_method, with the name of the method you are overloading. POST + http_method = put - makes it clear to your server side that the client requested a PUT over the resource.
To begin with, we will decipher KISS - keep it small and simple, for those who have not understood yet - stick to simple and small things, in other words, make it accessible and understandable to everyone and easily remembered.
To receive data from your web server, the client needs to know the URL at which it needs to contact. About the principles of "building" of these most universal resource pointers and will be discussed.
First of all, determine the basic set of rules that suits your service. For example, in our oDesk company, we indicated that the URIs whose base is / api are RESTful API resources. If you want your hey-pi-ai, you can put it on a separate subdomain, here it is worth remembering about cross-browser queries and other pitfalls that you will meet, even when querying “within” one domain.
The next point will be the creation of a resource router, an address at which it will be possible to access the data. We note several points that are considered to be a good manner when compiling an address:
- partitioning into idiomatic groups: mc - message center resources, team - command resources, etc.
for example: / api / mc / ...
- versioning
for example: / api / mc / v1 / ...
- a clear name of the resource to which access is granted
for example: / api / mc / v1 / prefs / ... - access to the settings of the message center
- entering persistent data under URL
for example: / api / mc / v1 / prefs / mydevelopersuid
- definition of the response format: either in the name of the URL of the router, or in the “system” variable
for example: /api/mc/v1/prefs/mydevelopersuid.json - oDesk uses the suffix “.json” when a response is required in JSON format, .xml is in XML format, and so on; / mc / v1 / prefs / mydevelopersuid? tqx = out: json - this is what Google does in GDS; / api / json / mc / v1 / prefs / mydevelopersuid is just another possible option, the format is part of the router.
Here you can talk a lot and for a long time, I will list the main points:
- always provide the opportunity to receive a response in json format. It so happened that in the world of AJAX applications, JSON * (3) became the de facto “standard” of data transfer between the client and server parts.
- use for authorization proven and proven schemes
Do not invent your scooter using md5 data signatures and other things, rely on data protection professionals. OAuth was invented for you, for it is full of libraries in different languages ​​- use this power. If you do not want OAuth, try APIKeys as implemented in Flickr. There are a couple of options - OpenID and others, I will not consider everyone - I told you the essence.
- do not forget about https, where it is needed
and, please, do not forget to specify in the documentation to your hey-pi-ai that your certificate is self-written, if it is. Appreciate the time of colleagues from the neighboring shop, so that they do not look for bugs in their applikuhah just because there is a check on the validity of the certificate.
- never “throw out” something unintelligible in the answer: errors of your web server, fatals, problems connecting to the database and so on. All of this should be handled by your RESTful web server and give a clear answer in the requested format. In other words, provide a distinct error responding to the client. The response format and headings are a separate topic. Returning correct HTTP statuses in accordance with RFC 2616 * (4) is considered a good practice, and if the status allows you to return a message body, the presence of a short message in the body. Some prefer to always give the status “200 OK” with the body, so the client should always parse the message and check the body for the presence of a message / tag about the error. Unambiguous practice and consensus yet!
- write documentation to your API, otherwise hey-pi-ah is useless :)
- and, finally, initially consider the internal architecture of the RESTful web service, the logic should be the same for any requested format, and data conversion should be done for each format separately. This will allow you to quickly and easily expand your routers, if necessary, add a new standard for displaying data.
being the main RESTful API developer at oDesk (API - developers.odesk.com is PR, take it, use it on your health! :)) and doing REST services for a long time, I think it was appropriate to share basic knowledge in this direction. Believing or not believing me is your personal right, but I still deeply hope that everyone who has read at least a little but will find the benefit for himself will at least refresh his knowledge;)
The REST architecture still leaves a lot of questions and not rarely leads to holivars, do not blame me if my opinion doesn’t coincide with yours.
PS article covers only basic aspects and does not claim to be a detailed instruction, a book, etc., for creating web services.
(1) http://en.wikipedia.org/wiki/Representational_State_Transfer
(2) http://en.wikipedia.org/wiki/Create,_read,_update_and_delete
(3) http://en.wikipedia.org/wiki/JSON
(4) http://www.w3.org/Protocols/rfc2616/rfc2616.html
Literature: RESTful Web Services (Leonard Richardson, Sam Ruby), O'Reilly Media, Inc.
Yahoo REST Group: http://tech.groups.yahoo.com/group/rest-discuss/
After reading the last few clumsy articles on the topic of WEB-services (for example: http://habrahabr.ru/blogs/development/108973/ ) and using REST technology in them, I decided that it was time to throw off the laziness, set aside time and write “ reformatted "in my head article.
So, briefly, what you will find in the article and to whom it will be useful:
- beginners who are interested in or plan to write a web service for the project
- pros are unlikely to find something new for themselves
- the general ideology of REST
- use of CRUD in WEB services
- KISS principles when building routers
- best practics
- a little PR;)
- references, literature
Where to begin to decide you, I recommend first reading the article, then google a little more, have a cup of tea / coffee / necessary_ emphasize, put your thoughts on the shelves and then start creating your hey pi-ah.
GENERAL IDEOLOGY
What is REST * (1)?
REST is “Representational State Transfer”, in other words, data representation in a format convenient for the client, by the client we mean client software from the client <-> server model.
In turn, web services created using the HTTP protocol and REST principles are called the RESTful web service.
An uninitiated person may immediately ask: why do we need such services? I will give a simple example based on REST and OAuth technologies: you have a gmail account and a dropbox account. Dropbox offers you extra space for each invited friend, but writing a letter manually and sorting through all the addresses from the gmail address book is not just boring, but also time consuming. Dropbox offers “come on, buddy, I will import contacts and send invitations”. It is clear that none of you will want to give your password from the box on the drop box. This is where the “magic” of RESTful web services comes into play. Using the API (hey-pi-ah, not “api”, as many used to say), dropbox makes a request to google web service, then “sends” you to google login page, so you enter your password in the form of google , Google authorizes you and lets you know (gives access_token) to dropbox about the success of the auth-process (authentication). In the end, having a unique token (access_token) and attaching it to each API request, dropbox has the ability to work with your personal data without knowing anything about your password.
It is important to remember that REST is not necessarily the use of the HTTP protocol, although initially the architecture was developed using just HTTP. REST can use any application layer protocol to transport data.
')
CRUD
When developing RESTful web services, it is important to remember about the CRUD * (2) methodology, which in the decrypted translation means: create-read-edit-delete (create-read-update-delete).
Since the development of web services is carried out using the HTTP protocol, you need to use its buns, namely: use the protocol methods to determine the action on the resource. The following standards are generally accepted in the REST world:
POST - create
GET - read (read, receive)
PUT - update (change, update or create, if it does not exist, it is sometimes used in this version)
DELETE - delete (delete)
It should be noted that the PUT and DELETE methods are difficult to implement, and due to the peculiarities of browsers, these methods are implemented “humanly” by AJAX on the client-browser side, and it also does not seem to work in all browsers. Therefore, it is accepted to use these methods by means of “overloading” the POST method. In other words: You send a reserved variable with the POST method, for example: http_method, with the name of the method you are overloading. POST + http_method = put - makes it clear to your server side that the client requested a PUT over the resource.
PRINCIPLES OF KISS WHEN BUILDING A RAUTER
To begin with, we will decipher KISS - keep it small and simple, for those who have not understood yet - stick to simple and small things, in other words, make it accessible and understandable to everyone and easily remembered.
To receive data from your web server, the client needs to know the URL at which it needs to contact. About the principles of "building" of these most universal resource pointers and will be discussed.
First of all, determine the basic set of rules that suits your service. For example, in our oDesk company, we indicated that the URIs whose base is / api are RESTful API resources. If you want your hey-pi-ai, you can put it on a separate subdomain, here it is worth remembering about cross-browser queries and other pitfalls that you will meet, even when querying “within” one domain.
The next point will be the creation of a resource router, an address at which it will be possible to access the data. We note several points that are considered to be a good manner when compiling an address:
- partitioning into idiomatic groups: mc - message center resources, team - command resources, etc.
for example: / api / mc / ...
- versioning
for example: / api / mc / v1 / ...
- a clear name of the resource to which access is granted
for example: / api / mc / v1 / prefs / ... - access to the settings of the message center
- entering persistent data under URL
for example: / api / mc / v1 / prefs / mydevelopersuid
- definition of the response format: either in the name of the URL of the router, or in the “system” variable
for example: /api/mc/v1/prefs/mydevelopersuid.json - oDesk uses the suffix “.json” when a response is required in JSON format, .xml is in XML format, and so on; / mc / v1 / prefs / mydevelopersuid? tqx = out: json - this is what Google does in GDS; / api / json / mc / v1 / prefs / mydevelopersuid is just another possible option, the format is part of the router.
BEST PRACTICS
Here you can talk a lot and for a long time, I will list the main points:
- always provide the opportunity to receive a response in json format. It so happened that in the world of AJAX applications, JSON * (3) became the de facto “standard” of data transfer between the client and server parts.
- use for authorization proven and proven schemes
Do not invent your scooter using md5 data signatures and other things, rely on data protection professionals. OAuth was invented for you, for it is full of libraries in different languages ​​- use this power. If you do not want OAuth, try APIKeys as implemented in Flickr. There are a couple of options - OpenID and others, I will not consider everyone - I told you the essence.
- do not forget about https, where it is needed
and, please, do not forget to specify in the documentation to your hey-pi-ai that your certificate is self-written, if it is. Appreciate the time of colleagues from the neighboring shop, so that they do not look for bugs in their applikuhah just because there is a check on the validity of the certificate.
- never “throw out” something unintelligible in the answer: errors of your web server, fatals, problems connecting to the database and so on. All of this should be handled by your RESTful web server and give a clear answer in the requested format. In other words, provide a distinct error responding to the client. The response format and headings are a separate topic. Returning correct HTTP statuses in accordance with RFC 2616 * (4) is considered a good practice, and if the status allows you to return a message body, the presence of a short message in the body. Some prefer to always give the status “200 OK” with the body, so the client should always parse the message and check the body for the presence of a message / tag about the error. Unambiguous practice and consensus yet!
- write documentation to your API, otherwise hey-pi-ah is useless :)
- and, finally, initially consider the internal architecture of the RESTful web service, the logic should be the same for any requested format, and data conversion should be done for each format separately. This will allow you to quickly and easily expand your routers, if necessary, add a new standard for displaying data.
PR
being the main RESTful API developer at oDesk (API - developers.odesk.com is PR, take it, use it on your health! :)) and doing REST services for a long time, I think it was appropriate to share basic knowledge in this direction. Believing or not believing me is your personal right, but I still deeply hope that everyone who has read at least a little but will find the benefit for himself will at least refresh his knowledge;)
The REST architecture still leaves a lot of questions and not rarely leads to holivars, do not blame me if my opinion doesn’t coincide with yours.
PS article covers only basic aspects and does not claim to be a detailed instruction, a book, etc., for creating web services.
LINKS *
(1) http://en.wikipedia.org/wiki/Representational_State_Transfer
(2) http://en.wikipedia.org/wiki/Create,_read,_update_and_delete
(3) http://en.wikipedia.org/wiki/JSON
(4) http://www.w3.org/Protocols/rfc2616/rfc2616.html
Literature: RESTful Web Services (Leonard Richardson, Sam Ruby), O'Reilly Media, Inc.
Yahoo REST Group: http://tech.groups.yahoo.com/group/rest-discuss/
Source: https://habr.com/ru/post/108993/
All Articles