2 Getting Started
2.1 ApiFest Overview
The ApiFest project consists of two main parts - ApiFest Mapping Server and ApiFest OAuth 2.0 Server. The project also includes ApiFest Doclet that will ease your work with ApiFest.
2.2 Minimum Requirements
ApiFest is written in pure Java and the only requirement to run it is to have JDK 1.6 installed or above. The current supported storages are MongoDB, Redis, Cassandra and Hazelcast (the default and out-of-the box storage).
2.3 Why ApiFest?
ApiFest is designed to aid developers in their daily work related to API changes, API publishing and API security. ApiFest does not require a special IDE - developers can use their favorite one. Also, ApiFest does not require any product specific knowledge - no steep learning-curve to start using it, it is a simple Java program - you checkout the code, compile it and start it or download the compiled version and start it. In contrast to many products for API publishing, the API publishing in ApiFest is not done by clicking in a special IDE or API Gateway, it uses a simple and clean XML format that could be easily generated. The generation of the API configuration, so called mappings configuration, could be made by using ApiFest Doclet that reads specific Javadoc annotations in your code. You can see the list of the main ApiFest features below.
FeaturesApiFest features could be separated in two main groups - API security and API management.
API Security- OAuth 2.0 support
- Dynamically configured OAuth 2.0 scopes
- Configurable expiration period of OAuth 2.0 access tokens and refresh tokens per OAuth20 scope
- Revocation of access tokens
- Custom user authentication
- Custom grant type supported
- Custom lifecycle events handlers
- API model (XML format) could be generated from Javadoc using ApiFest Doclet
- Native support for multiple API versions and backend hosts
- Customizable error responses
- Request and response transformations are implemented as simple Java classes
2.4 ApiFest Inside
As previously said, ApiFest project consists of two main parts - ApiFest Mapping Server and ApiFest OAuth 2.0 Server. ApiFest Mapping Server exposes your API in a safe and convenient way. It is used to translate the requests between the public API and your internal API.
The description of the API that will be exposed through the ApiFest Mapping Server is in XML format. The file that describes the API is called mappings configuration file. As an API usually consists of different parts and supports several versions, the mappings configuration in ApiFest could be split in several files. The format of the file is described in chapter 3.2. Note, that the mappings configuration file could be automatically generated by ApiFest Javadoc annotations in your code using ApiFest Doclet (see chapter 3.7).
In order to secure your API, the ApiFest OAuth 2.0 Server is used. It implements OAuth 2.0 server side as per the RFC6749 (http://tools.ietf.org/html/rfc6749) and enables the usage of access tokens in the ApiFest Mapping Server, i.e. in order to access a resource in your API, a valid access token should be provided. On the diagram below, you can see how the ApiFest Mapping Server and the ApiFest OAuth 2.0 Server work together to create a layer in front of your API. Each API request passed through the ApiFest Mapping Server, then a call to the APiFest OAuth 2.0 Server is made in order to validate the access token (if required), a request transformation is performed in the ApiFest Mapping Server (if necessary) and then if the access token is valid the request is passed to your system - backend API. All requests from the client applications that are related to OAuth 2.0 are handled by the ApiFest OAuth 2.0 Server.
On the diagram below you can see a sample flow with ApiFest layer consisting of many ApiFest Mapping Server instances and ApiFest OAuth 2.0 Server instances. Here, the inner calls between the ApiFest Mapping Servers and the ApiFest OAuth 2.0 Servers are skipped.
Below is a physical diagram that represents usage of ApiFest. There are several different nodes that run ApiFest Mapping Server and ApiFest OAuth 2.0 Server (called only ApiFest for simplicity) and a load balancer in front of them. All API requests go to the load balancer and it redirects them depending on whether the request is an OAuth 2.0 or not. Then each ApiFest node either passes the request to the backend API or calls user authentication in the backend API in order to issue an access token. Of course, the user authentication may happen outside of the backend API. This is just an example.
