Note

forms-api is now deprecated and is no longer a core part of the GOV.UK Forms service. This repository will be archived in the near future. Consider this document out of date and only of use for historical purposes.

GOV.UK Forms - API

forms-api is the API for the GOV.UK Forms platform. It is a Ruby on Rails api app, currently using a Postgresql database for data storage and is used for storing/serving the form configurations that are created by form creators in forms-admin.

Before you start

To run the project you will need to install:

• Ruby - we use version 3.1 of Ruby. Before running the project, double check the [.ruby-version] file to see the exact version.
• a running PostgreSQL database

We recommend using a version manager to install and manage these, such as:

• asdf for Ruby (and many other languages)
• RVM or rbenv for Ruby

Getting started

Installing for the first time

# 1. Clone the git repository and change directory to the new folder
git clone git@github.com:alphagov/forms-api.git
cd forms-api

# 2. Run the setup command
./bin/setup

Running the app

# Running the server without watching for changes
bundle exec rails s

This will start the server on localhost:9292

Configuration and deployment

The forms-api app is containerised (see Dockerfile) and can be deployed however you would normally deploy a containerised app.

Testing the project

# Run the Ruby test suite
bundle exec rake

Secrets vs Settings

Refer to the the config gem to understand the file based settings loading order.

To override file based via Machine based env variables settings

cat config/settings.yml
file
  based
    settings
      env1: 'foo'

export SETTINGS__FILE__BASED__SETTINGS__ENV1="bar"

puts Settings.file.based.setting.env1
bar

Refer to the settings file for all the settings required to run this app

Feature flags

This repo supports the ability to set up feature flags. To do this, add your feature flag in the settings file under the features property. eg:

features:
  some_feature: true

You can then use the feature service to check whether the feature is enabled or not. Eg. FeatureService.enabled?(:some_feature).

You can also nest features:

features:
  some:
    nested_feature: true

And check with FeatureService.enabled?("some.nested_feature").

Testing with features

Rspec tests can also be tagged with feature_{name}: true. This will turn that feature on just for the duration of that test.

Logging

• HTTP access logs are managed using Lograge and configured within the application config
• The output format is JSON using the JsonLogFormatter to enable simpler searching and visbility especially in Splunk.
• DO NOT use log_tags since it breaks the JSON formatting produced by Lograge.

Updating versions

Use the update_app_versions.sh script in forms-deploy

Support

Raise a Github issue if you need support.

How to contribute

We welcome contributions - please read CONTRIBUTING.md and the alphagov Code of Conduct before contributing.

License

We use the MIT License.