README

API-only Rails app generated using the command:

rails new allsearch_api --api --skip-javascript --skip-asset-pipeline --skip-spring --skip-test --no-rc --skip-active-record

Requires:

• Ruby 3.2

Getting started

1. Clone the repository - git clone git@github.com:pulibrary/allsearch_api.git
2. Go to the repository directory - cd allsearch_api
3. Install the required ruby version - asdf install
4. Install the required gems - bundle install
5. Make sure you have wget installed - brew install wget
6. Start local solr and postgres - bundle exec rake servers:start
7. Start the application server on localhost:3000 - bundle exec rails s
8. See the application running at http://localhost:3000/

Run tests

RSpec

bundle exec rspec

Rubocop

bundle exec rubocop

Reek

bundle exec reek

Semgrep

This repository uses semgrep to:

• Perform static security analysis

To run semgrep locally:

brew install semgrep
semgrep --config auto . # run rules from the semgrep community

Create a new service

1. If the upstream service requires a secret, add it to the vault and environment variables using a princeton_ansible pull request
2. Create a new request spec for your service, based on the other service request specs
3. Create a new route in config/routes

   get '/search/new_service/', to: 'new_service#show', defaults: { format: 'json' }

4. Create a new controller for your service. You can inherit from ServiceController and/or implement your own #show method.
5. Create a controller spec to confirm that query inputs are sanitized appropriately.
6. Create a model to represent a request to the upstream service. Include the Parsed module in your model.
7. Create a model to represent a document returned by the upstream service. This should inherit from Document and implement a #doc_keys method.
   • #doc_keys should return a list of fields (as symbols) that will be presented in allsearch's API response. Each symbol should match the name of a method in this model.
8. Create an API spec for your service in spec/requests/api/
9. Generate the swagger docs as described below.
10. If the service uses solr, add some sample data.

API documentation

Documentation lives in https://allsearch-api.princeton.edu/api-docs

To update the api documentation for a service:

• create a spec in: spec/requests/api/
  • ./bin/rails generate rspec:swagger CatalogController --spec_path requests/api/
  • Do the necessary changes to create the swagger doc based on the spec.
• Generate the docs by running:
  • bundle exec rake rswag:specs:swaggerize.
  • This will generate the file swagger/v1/swagger.yaml.
  • Please make sure to commit it.
• Visit the documentation:
  • Documentation

Validating the Swagger/OpenAPI schema file

This repo uses vacuum to validate that the swagger.yaml file meets the OpenAPI standard.

brew install daveshanley/vacuum/vacuum
vacuum lint -d swagger/**/*.yaml

Update the banner

In order to update the banner at /banner, you can either update it on the rails console, or use a rake task.

Valid values for 'alert_status' are info|success|warning|error

Run the rake task

There is a rake task that can accept multiple arguments. The arguments are [text, alert_status, dismissible, autoclear]. The arguments are comma delimited, with no spaces. If there is an argument you want to skip, just leave it blank, but leave any commas that might surround it (similar to a csv file). Depending on your shell, you may need to escape the brackets surrounding the arguments.

If there are any commas in your text, you will need to escape them using \

Setting all four values:

bundle exec rake banner:update\['new banner',info,true,true\]

Setting only text and autoclear

bundle exec rake banner:update\['newer banner',,,false\]

Setting long text in multiple steps

LONG_HTML="<h2>All-Search Updated</h2><p> Introducing our new and improved All-Search\, upgraded with advanced technology and designed based on your feedback to enhance your research experience. Share your experience and help us improve it further by completing this <a href='https://example.com'>brief survey</a></p>"
bundle exec rake banner:update\["$LONG_HTML",'info',true,false\]

Set the banner to visible or not visible

Via Capistrano

Can be run locally against a remote environment. Must be on VPN.

bundle exec cap staging banner:enable
bundle exec cap staging banner:disable

Via the Flipper CLI

Must be done on the environment where you want to change it

bundle exec flipper enable banner
bundle exec flipper disable banner

Use the permanent website url

Via the Flipper CLI

Must be done on the environment where you want to change it

bundle exec flipper enable permanent_host # sets library host to library.princeton.edu
bundle exec flipper disable permanent_host # sets library host to library.psb-prod.princeton.edu