A little bit about how to organize the web service API
There was a task to organize a web service, which will be accessed by ordinary clients from a browser and other web services.
Suppose I sell theater tickets to clients. A client can only be an agency that has its own account on my service. Agencies are small, in which an aunt sits and handles in his personal account with the help of a baruzer, he buys a ticket, as well as large ones, in which everything is automated. Big ones want to be able to connect to me using the API and make a purchase.
You can look at prices for tickets, pre-book, redeem a reservation, return purchased and delete a reservation.
Question: what is the best way to organize an API?
I am going to organize a web service and, in general, a Ruby on Rails service, but I will try to state general principles where it is possible to bypass the implementation. I will try to summarize what I read in the process of preparing for the creation of the API, as well as provide links to the source.
By architecture / ideology options: REST , SOAP , XML-RPC and others.
After reading a lot, I chose REST, because it gives less freedom in places where it is not needed: the name of the methods and the method of calling this method. Briefly: my tickets are now resources. Each action with a ticket is available through a unique combination of HTTP method + URL. For example, pre-booking (in essence, creating a ticket order): POST /orders.xml, deleting a ticket order DELETE /orders/1.xml, and viewing prices GET /prices.xml.
Read more about REST on Habr and on Wikipedia .
The best open source REST and Ruby on Rails API article is the ActiveResource chapter in the book.Rails 3 in a Nutshell , courtesy of O'Reilly. It describes the situation from the point of view of both the REST API client and the server. It is very useful to read to understand why it is necessary to use the RESTful API. In addition, it describes a very interesting implementation of the ActiveResource REST API client included with Ruby On Rails. ActiveResource is ported to some other languages and will be useful not only to rubists.
The rest of the articles read, after deduction of trifles, are invested in the one above.
By implementation, I really liked the concept offered by Rails by default, and it exploited the DRY principle with all its might : generating API responses (XML, JSON) in the same controllers as generating user responses (html).
By the way, for implementing DRY, there is a useful acts_as_api plugin that allows you to save a lot on XML templates and a new Ruby on Rails 3 feature .
There are several sensible branches on Stackoverflow on this topic, for example this one .
There are several DSLs for organizing an API. For example, Grape, and if anyone needs to integrate Grape and Ruby on Rails, then here: martinciu.com/2011/01/mounting-grape-api-inside-rails-application.html
There are a lot of authentication / authorization options: Basic , with the help of tokens, with the help of certificates, Oauth .
As far as I figured out in Oauth, in our case it does not fit, because there is no client account on my server that could allow the agent to log in. There is no end user at all, I don’t know about him, so the option with Oauth disappears.
The most reliable in terms of security, but, apparently, the most difficult to implement, both on the client and on the server, is authentication based on certificates.
The most basic option is basic (essentially a username and password: user : password@api.myserver.ru/orders.xml).
I chose the option of authentication by stateless tokens, as this allows the user to log in to the browser with a username and password and create orders and, at the same time, create orders using the automated web service under the same user (but through a token). I want each of my agents to have exactly one user on my server.
Yes, of course, do not forget that since we started to log in, our API should be wrapped in HTTPS in order to avoid authorization data leaks. I plan to enable my agents to regenerate the API key in their personal accounts, if they consider that it is time.
In addition, I chose the stateless token option, passed as a POST or GET parameter. There is another option to shove token into HTTP headers, and not by a parameter (this is a more REST version, but a little more difficult to implement), as Amazon did . But it seemed to me that in this case the implementation game is not worth the candle. There is no particular gain for this option (well, maybe, except that the request structure
will become a little more RESTful), but there is a hassle.
Web service authorization / authentication literature:
stackoverflow.com/questions/6134082/restful-web-service-how-to-authenticate-requests-from-other-services
stackoverflow.com/questions/939836/service-based- authentication-using-tokens
There is a wonderful devise plugin for Ruby on Rails , for which there is a module for authentication by token . Literally, a couple of lines - and you're done.
UPD Colleagues minus the topic, you at least unsubscribe with what disagree. And then half the value of the topic is in the discussion, and you are silent!
Suppose I sell theater tickets to clients. A client can only be an agency that has its own account on my service. Agencies are small, in which an aunt sits and handles in his personal account with the help of a baruzer, he buys a ticket, as well as large ones, in which everything is automated. Big ones want to be able to connect to me using the API and make a purchase.
You can look at prices for tickets, pre-book, redeem a reservation, return purchased and delete a reservation.
Question: what is the best way to organize an API?
I am going to organize a web service and, in general, a Ruby on Rails service, but I will try to state general principles where it is possible to bypass the implementation. I will try to summarize what I read in the process of preparing for the creation of the API, as well as provide links to the source.
API Organization Principles
By architecture / ideology options: REST , SOAP , XML-RPC and others.
After reading a lot, I chose REST, because it gives less freedom in places where it is not needed: the name of the methods and the method of calling this method. Briefly: my tickets are now resources. Each action with a ticket is available through a unique combination of HTTP method + URL. For example, pre-booking (in essence, creating a ticket order): POST /orders.xml, deleting a ticket order DELETE /orders/1.xml, and viewing prices GET /prices.xml.
Read more about REST on Habr and on Wikipedia .
The best open source REST and Ruby on Rails API article is the ActiveResource chapter in the book.Rails 3 in a Nutshell , courtesy of O'Reilly. It describes the situation from the point of view of both the REST API client and the server. It is very useful to read to understand why it is necessary to use the RESTful API. In addition, it describes a very interesting implementation of the ActiveResource REST API client included with Ruby On Rails. ActiveResource is ported to some other languages and will be useful not only to rubists.
The rest of the articles read, after deduction of trifles, are invested in the one above.
Implementation
By implementation, I really liked the concept offered by Rails by default, and it exploited the DRY principle with all its might : generating API responses (XML, JSON) in the same controllers as generating user responses (html).
By the way, for implementing DRY, there is a useful acts_as_api plugin that allows you to save a lot on XML templates and a new Ruby on Rails 3 feature .
There are several sensible branches on Stackoverflow on this topic, for example this one .
Implementing the API as a standalone module
There are several DSLs for organizing an API. For example, Grape, and if anyone needs to integrate Grape and Ruby on Rails, then here: martinciu.com/2011/01/mounting-grape-api-inside-rails-application.html
Authentication
There are a lot of authentication / authorization options: Basic , with the help of tokens, with the help of certificates, Oauth .
As far as I figured out in Oauth, in our case it does not fit, because there is no client account on my server that could allow the agent to log in. There is no end user at all, I don’t know about him, so the option with Oauth disappears.
The most reliable in terms of security, but, apparently, the most difficult to implement, both on the client and on the server, is authentication based on certificates.
The most basic option is basic (essentially a username and password: user : password@api.myserver.ru/orders.xml).
I chose the option of authentication by stateless tokens, as this allows the user to log in to the browser with a username and password and create orders and, at the same time, create orders using the automated web service under the same user (but through a token). I want each of my agents to have exactly one user on my server.
Yes, of course, do not forget that since we started to log in, our API should be wrapped in HTTPS in order to avoid authorization data leaks. I plan to enable my agents to regenerate the API key in their personal accounts, if they consider that it is time.
In addition, I chose the stateless token option, passed as a POST or GET parameter. There is another option to shove token into HTTP headers, and not by a parameter (this is a more REST version, but a little more difficult to implement), as Amazon did . But it seemed to me that in this case the implementation game is not worth the candle. There is no particular gain for this option (well, maybe, except that the request structure
will become a little more RESTful), but there is a hassle.
Web service authorization / authentication literature:
stackoverflow.com/questions/6134082/restful-web-service-how-to-authenticate-requests-from-other-services
stackoverflow.com/questions/939836/service-based- authentication-using-tokens
Implementation
There is a wonderful devise plugin for Ruby on Rails , for which there is a module for authentication by token . Literally, a couple of lines - and you're done.
UPD Colleagues minus the topic, you at least unsubscribe with what disagree. And then half the value of the topic is in the discussion, and you are silent!