Difference between revisions of "stoney core: REST API"
| [unchecked revision] | [unchecked revision] |
(→Base URI) |
(→Base URI) |
||
| Line 40: | Line 40: | ||
== Service implementation details == | == Service implementation details == | ||
=== Base URI === | === Base URI === | ||
| − | The RESTful web service has to be accessible via a secure HTTP (HTTPS) base URI, for instance <code>https://api.example.com/v1/ | + | The RESTful web service has to be accessible via a secure HTTP (HTTPS) base URI, for instance <code>https://api.example.com/v1/customers</code>. |
The definition of the base URI is up to the provider of the service. The only requirements are the use of HTTPS and the presence of the service's version information, so that further changes are possible without breaking existing clients. | The definition of the base URI is up to the provider of the service. The only requirements are the use of HTTPS and the presence of the service's version information, so that further changes are possible without breaking existing clients. | ||
Revision as of 11:19, 13 November 2013
Contents
REST API
- The REST API will be implemented as a first-class citizen
- It provides all the available functions and data to its clients
- Serves as a data and business logic abstraction layer
- The REST API will be implemented using HTTPS and REST principles
- The REST API uses JSON as the primary data interchange format (serialization of data structures should be abstracted), other formats should be possible in the future.
- Multiple authentication methods are possible
- Web-Server assisted:
- Basic HTTP-Auth
- X509 Certificate based authentication
- Kerberos
- API key with shared secret
- Access tokens
- Web-Server assisted:
- versioned API (either via URI or the Accept-Header)
- All API calls need to be fully nonblocking. If an expensive call has to be made to a backend system, the client needs to be provided with a status URI which can be checked for the current status or preferably be notified via WebSockets.
- Input validation must be performed for all data (validation of data happens twice: in the API and the client)
- Meaningful error message will be presented to the client
- All API functions are to be documented using an accepted documentation standard (doxygen (preferred), phpDocumentor or Sami)
- The API will be based on existing, proven and tested open source modules and components, coming either from a framework are as stand alone implementations,
Why a REST API?
- Separation and abstraction of presentation and business logic
- Faster development/test cycles for business logic
- Smaller development packages
- Support for multiple clients with the same code base
- HTML/JS/CSS for selfcare Web GUI
- Command line interface for easy scripting
- Integration into third party provisioning systems for resellers
- Automatic testing of functionality
- Base for responsive resp. Mobile First Web-Applications/-Design
- On the Yii PHP Framework Homepage: Extensions tagged with "rest"
- On the Yii PHP Framework Homepage: RestfullYii or on GitHub: RestfullYii
- On the Yii PHP Framework Homepage: Extensions tagged with "api"
- yii-apiauth
Service implementation details
Base URI
The RESTful web service has to be accessible via a secure HTTP (HTTPS) base URI, for instance https://api.example.com/v1/customers.
The definition of the base URI is up to the provider of the service. The only requirements are the use of HTTPS and the presence of the service's version information, so that further changes are possible without breaking existing clients.
Client authentication
The service needs to authenticate each client via HTTP basic authentication by a user name and a corresponding password.
Data interchange format
The service needs to accept and send all data in the JSON data interchange format via HTTP, encoded as UTF-8. Thus a client needs to accept and use the application/json media type. Further media types might be supported in the future.
Error codes and responses
The service needs to return appropriate HTTP status codes for every request, the following table lists the commonly used codes:
| HTTP status code | Text | Description |
|---|---|---|
| 200 | OK | Success. |
| 201 | Created | A new resource was successfully created. |
| 400 | Bad Request | The request was invalid. A descriptive error message will be sent within the response body. |
| 404 | Not Found | The requested resource could not be found but may be available again in the future. |
| 406 | Not Acceptable | The requested resource is only capable of generating content not acceptable according to the Accept headers sent in the request. |
| 401 | Unauthorized | The client has failed or not yet tried to authenticate. |
| 403 | Forbidden | The client is not allowed to access the requested resource. |
| 500 | Internal Server Error | An internal error succoured. A descriptive error message will be sent within the response body. |
| 503 | Service Unavailable | The service is temporary unavailable, because it is overloaded or down for maintenance |
Additionally the service returns descriptive error objects within the message body of the response. An error object consists of an error code and a human readable error message.
TBD.
