REST API

Petal Pro comes with a pre-built REST API. Though it is limited in scope, the API has been created so that it is easy to extend

The REST API is a sample API that has been created for user management. For example, you could use the API with a mobile application to register a user, sign them in and update their profile.

Though the API is provided as an example, it can be easily extended or updated. The key to this extensibility is the selection of technologies:

• The Phoenix Framework provides first-class support for creating APIs
• phx.gen.auth is used as a basis for API Authentication
• Open API support via Open API Spex

Taking Advantage of the Phoenix Framework

With the Phoenix Framework, you can use the following command to generate a JSON API:

This creates a set of files that take care of the database schema, data access control, the JSON for the output and testing. All you are required to do is add the suggested route to the /api scope. This provides a complete/comprehensive starting point for your own work.

## A Word on Authentication With regards to securing a HTML web page, authentication is stateful. That is, authentication involves user interaction (e.g. via a HTML form) and state is maintained via methods such as maintaining session state on the server and storing essential data in a browser cookie. API authentication, on the other hand, is usually stateless and does not involve direct interaction with the end user. Authentication is usually about authorising a client (application or server) - rather than an individual. This process is handled programmatically between systems and enough data must be sent with each call to achieve authentication. For example, a mobile app may have a client that communicates with the API server. ## The Petal Pro Sample API Token Following the recommendations in the Phoenix Framework [API Authentication](https://hexdocs.pm/phoenix/api_authentication.html) documentation, client devices/services can access the API if they provide a valid API token. However, the API has been created so each user can generate their own token. The "Register", "Send Instructions" and "Sign In" API calls do not require an API token. If you sign In successfully, an API token is supplied. You can use the token from the "Sign In" call for the other API calls. API calls protected by a token are locked down to that particular user. For example, even if you're an admin user, you can't view the profile of another user. As an alternative, you could create a page in the website where users can generate their API token. You could use this mechanism to tie a client application to an account. However, this would require a change in logic for the API calls (i.e. you would need to allow this user to view/change any user). ## Support for Open API Support for Open API has been added via [Open API Spex](https://hexdocs.pm/open_api_spex). Existing API calls are decorated with meta data that provides enough information to generate an Open API spec. For example, here is a cut down version of the "Sign In" call: ```elixir operation :create, summary: "Authenticate user", description: "Authenticate user and generate bearer token", request_body: {"User credentials", "application/json", Schemas.UserCredentials}, responses: [ ok: {"Authenticated response", "application/json", Schemas.AuthResponse}, unauthorized: %Reference{"$ref": "#/components/responses/unauthorised"} ] def create(conn, %{"email" => email, "password" => password}) do # ... end ``` The `operation` macro allows you to keep your Open API spec with your API call - yet keep them logically separated. The general configuration for the Open API spec can be found in `/lib/petal_pro_api/api_spec`. It's used to configure things like the title, version or type of authorisation used in the API. It also defines standard responses. For example, it defines the `unauthorised` response that the above code snippet is referring to. One of the benefits of the Open API spec is that it can be used to generate a UI for testing. To see the SwaggerUI, navigate to: ```css http://localhost:4000/dev/swaggerui ``` The spec itself can be found at: ```css http://localhost:4000/api/openapi ``` You can use this with 3rd party tools to generate code or documentation for an API client. Check out the [documentation](https://hexdocs.pm/open_api_spex) for more details on how to configure your API code with Open API Spex. ## Directory Structure The Petal Pro API has been separated into it's own directory structure. This is relevant to the `/lib` and `/test` directories: ```elixir ├── lib │ ├── petal_pro │ ├── petal_pro_api | | ├── controllers | | ├── api_spec.ex | | ├── routes.ex | | ├── schemas.ex │ ├── petal_pro_web ├── test │ ├── petal_pro │ ├── petal_pro_api │ ├── petal_pro_web ``` For the `/lib/petal_pro_api` directory: - `controllers` is where the API methods are kept - `api_spec.ex` is the starting point for Open API Spex (see above) - `routes.ex` is where the API routes are defined. This is included in `/lib/petal_pro_web/router.ex` - `schemas.ex` are the data models that are used by the Open API Spex definition ## Creating you're own API To get your hands dirty with the sample API, see the following: [Creating Your Own API](/petal-pro/guides/creating-your-own-api)