API for notifications service (notfications-as-a-service or NAAS) prototype
Requirements:
- Ruby 2.0+
- Bundler
- Ngrok or localtunnel if you wish to send live messages.
- Note: these tools are likely not approved for use on any government network.
- Configure application secrets in
/config/secrets.yml
- If you'd like to send live messagse, you will need to register for API credentials and a phone number with Twilio.
- Bundle application dependencies with
bundle
,
- Install the latest version of bundler with
gem install bundler
- Setup the database with
rake db:setup db:migrate
- Start the server with
bin/rails s
and your application will be running at http://localhost:3000
- To run the suite of specs, simply run
rake
.
- Install the CloudFoundry client and authenticate with cloud.gov.
- For help, visit Set up the command line in the cloud.gov documentation.
- The name of the application can be defined with the environment variable
APP_NAME
, otherwise, it will be deployed asnaas-api
upon executingbin/cf_push
.
Retrieve API credentials from server:
curl -H "Content-Type: application/json" -X POST -d '{"email":"[email protected]","password":"123123123"}' http://localhost:3000/authenticate
This will return the api key to use in future requests:
{"auth_token":"eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjo0LCJleHAiOjE1MTU3OTUxNzZ9.JN7aLcS1l7PS6GPE0B5KA7iozZ4AIClNa3wtb7yuviI"}
First let's create a user
curl -H "Content-Type: application/json" -H "Authorization:eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjo0LCJleHAiOjE1MTU3OTUxNzZ9.JN7aLcS1l7PS6GPE0B5KA7iozZ4AIClNa3wtb7yuviI" -X POST -d '{"last_name": "Marsh", "email": "[email protected]", "password":"evenfakerer","password_confirmation":"evenfakerer", "phone": "1234567"}' http://localhost:3000/users
The endpoint will return json of the newly created resource if the operation was successful
{"id":5,"email":"[email protected]","first_name":null,"middle_name":null,"last_name":"Marsh","phone":"1234567","created_at":"2018-01-11T22:25:53.282Z","updated_at":"2018-01-11T22:25:53.282Z","password_digest":"$2a$10$OIxhT7T6GzVmVJ/b761zM.GwxD0gcD/y8P.Um8cwI.kTfiIo4yD0e","name":null,"confirmed":null}
Now let's create a sample notification. Agencies can have multiple notifications that multiple users can subscribe to.
curl -H "Content-Type: application/json" -H "Authorization:eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjo0LCJleHAiOjE1MTU3OTUxNzZ9.JN7aLcS1l7PS6GPE0B5KA7iozZ4AIClNa3wtb7yuviI" -X POST -d '{ "name": "General Alert", "created_by":"1" }' http://localhost:3001/notifications
The created_by column is the id of the Agency user creating the notification
With users and notifications added to the application we now demonstrate a user subscribing to a notification.
curl -H "Content-Type: application/json" -H "Authorization:eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjo0LCJleHAiOjE1MTU3OTUxNzZ9.JN7aLcS1l7PS6GPE0B5KA7iozZ4AIClNa3wtb7yuviI" -X POST -d '{ "name": "General Alert", "user_id":"1" }' http://localhost:3001/notifications/3/user_subscriptions
This request, in plain language, can be read as the user with id of 1
subscribed to notification 3 (the notification)
we just created), this notification is maintained by its related agency.
Before a user can receive SMS alerts they must first confirm their mobile phone number, by submitting their number as follows.
curl -H "Content-Type: application/json" -H "Authorization:eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjo0LCJleHAiOjE1MTU3OTUxNzZ9.JN7aLcS1l7PS6GPE0B5KA7iozZ4AIClNa3wtb7yuviI" -X POST -d '{"phone": "8082246036",
"body":"A Sample Subscribe Message", "source_app": "my_app_name"}' http://localhost:3001/subscribe
The user will then receive a message that they must respond to for confirmation, the language of this message can be customized at the agencies request. Once the user responds their profile is marked as confirmed to receive SMS messages.
For now an Agency can send a group or targeted message by activing a notification by sending an HTTP POST as follows, the agency can provide the message body in the request, if a message is not provided the notification will be sent with a body that was saved with the notification when it was created.
curl -H "Content-Type: application/json" -H "Authorization:eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjo0LCJleHAiOjE1MTU3OTUxNzZ9.JN7aLcS1l7PS6GPE0B5KA7iozZ4AIClNa3wtb7yuviI" -X POST -d '{ "body": "Hello from NAAS"}' http://localhost:3001/notifications/3/send_group_notification
This project is in the worldwide public domain. As stated in CONTRIBUTING:
This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.
All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.