🔢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:

Taking Advantage of the Phoenix Framework

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

mix phx.gen.json Urls Url urls link:string title:string

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.

The Phoenix generator will put your controller under:

/lib/petal_pro_web/controllers

This isn't a problem, but you might like to move it to where the other API controllers are:

/lib/petal_pro_api/controllers

The same is true for the test that's generated. See Directory Structure (below) for more details

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 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. 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:

session_controller.ex
  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:

http://localhost:4000/dev/swaggerui

The spec itself can be found at:

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 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:


├── 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:

PreviousTesting