Generator

When you setup stitches, you should have run the stitches:api generator. This does some useful setup for you:

Ping endpoint

The generator creates two controllers: Api::V1::PingsController and Api::V2::PingsController, and sets up your app to respond on the route /api/ping. This endpoint exists to let you validate your app and client library.

To validate:

1. Generate an API key using the rake task

   > bundle exec rake generate_api_key[api client validation]
   

2. This will produce a UUID that is a valid API key. Use that when constructing a curl invocation:

   > curl -v -X POST -H 'Accept: application/json; version=1' \
                     -H 'Content-type: application/json; version=1' \
                     -H 'Authorization: CustomKeyAuth key=«the api key»' \
                     http://«your_app»/api/ping"
   

3. This should return JSON like { ping: { status: "ok" }

4. Repeat for version 2:

   > curl -v -X POST -H 'Accept: application/json; version=2' \
                     -H 'Content-type: application/json; version=2' \
                     -H 'Authorization: CustomKeyAuth key=«the api key»' \
                     http://«your_app»/api/ping"
   

5. This will hit the other controller and produce JSON like { ping: { status_v2: "ok" } }

6. The ping endpoints recognize two query parameters:

   • error- If set, you will get a structured error message container the value for error and an HTTP status of 422
   • status - If set, you will get this value back as the HTTP status instead of 201

With this information, you can validate that your server is deployed properly, and you can also use it to implement your API client in whatever language you like.

Versioned Routes

As implied above, versioning will hit different controllers. Your config/routes.rb will be set up for both V1 and V2. This isn't because you should start writing V2 endpoints, but more to demonstrate how it works. By the time you need to version, you will have forgotten that you are even using stitches, so the setup in config/routes.rb will help.

  scope module: :v1, constraints: Stitches::ApiVersionConstraint.new(1) do
    resource 'ping', only: [ :create ]
    # Add your V1 resources here
  end
  scope module: :v2, constraints: Stitches::ApiVersionConstraint.new(2) do
    resource 'ping', only: [ :create ]
    # This is here simply to validate that versioning is working
    # as well as for your client to be able to validate this as well.
  end
end

Api Clients

There should be a database migration to create the API_CLIENTS table. Stitches will also add code to Api::ApiController to fetch the entry from that table with each request, based on the contents of the Authorization header. You can access it via the method api_client. It will also alias current_user so that if you other tooling that expects a current_user to exist, such as logging, it will show the API client ID (not key) for each request.

API Documentation

Stitches will have configured rspec_api_documentation and some basic tests in spec/acceptance. These are your integration tests and will produce documentation.

The documentation is served up via apitome, meaning you can browse the docs online. The generator will hide this behind HTTP Auth, configured like so:

api_docs = Rack::Auth::Basic.new(Apitome::Engine ) do |_,password|
  password == ENV['HTTP_AUTH_PASSWORD']
end
mount api_docs, at: "docs"

In your production environment, set HTTP_AUTH_PASSWORD to something and you can view the docs online.