The First RichCoin Bank of Santa Barbara CS290B – Spring 2014 Hiranya – Alex – Chris – Emre - Stratos

Roadmap Introduction APIs Tutorial and demo AWS for RichCoin Questions

Introduction Central storage for all the RichCoins you’re going to mine this quarter. Validates submitted coins for correctness and uniqueness. Keeps score. Accessible via a secure REST API.

System Design Web Server Database Queue Coin Validator Client (You) Client (You)

API Features Secured – OAuth 2.0 bearer token profile Throttled (Rate Limited) – Gold, Silver and Bronze tiers Separate production and sandbox environments Versioned

APIs Vault API – Mint new coins – Retrieve already minted coins Scoreboard API – Retrieve current score Admin API – Only for admins

Accessing the APIs: Step 1 Send an to Specify following details: –Group name: avengers2014 –Group members: Steve Rogers Tony Stark Bruce Banner You will get a reply back with login credentials for the RichCoin API Store.

Accessing the APIs: Step 2 Change your password… Login using the username and password sent in the . Click on “Configure” tab left to the main menu. Select “Users and Roles”. Click on “Change My Password”.

Accessing the APIs: Step 3 Register your applications… Login using your username and password. Select “My Applications”. Enter a meaningful name for the application you’re going to implement using the APIs.

Accessing the APIs: Step 4 Subscribe to the APIs… Click on each API, select the application you registered in the previous step, select a throttling tier and click “Subscribe”.

Accessing the APIs: Step 5 Obtain API keys… Select “My Subscriptions”. Make sure your application is selected in the dropdown. Click “Generate Keys”. – You can generate separate keys for production and sandbox environments.

Accessing the APIs: Step 6 At this point you are all set. Simply send your API key to the server along with all your requests. API key should be sent as a HTTP Authorization header: – Authorization: Bearer

Production & Sandbox Setups You can get separate keys to access the production and sandbox environments. APIs and their URLs are identical in the two environments. Use the sandbox environment to test your application. For the contest we will only consider the score in the production environment. Note: Sandbox environment is not backed up and your data may get lost.

Throttling/Rate Limiting The access tier you selected when subscribing to an API determines how many requests you can send to an API in a minute. – e.g. Gold tier: Allows 20 req/minute Once you exceed your per-minute quota, you will start receiving errors (503 Service Unavailable).

Vault API Minting a new coin POST a JSON payload to /vault/1.0.0 – solution: Your solution matrix encoded into a string of 1’s and 0’s (row-major form) – clientTimestamp: A UTC timestamp generated from the client machine (milliseconds since epoch) { “solution”: “ ”, “clientTimestamp”: }

Vault API: Response When you submit a new solution, you will get a unique ID back in return. Use this ID to query the status of your solution. – GET /vault/1.0.0/ { “coinId” : “1ab3jshfshns”, “ status” : 0, …. }

Scoreboard API Retrieve the current score Send a GET request /scoreboard/1.0.0 You get a JSON payload back with all the users and the number of coins they have mined – Application details available in payload for each user – Scores are sorted in descending order

API Quick Reference API CallDescription POST /vault/1.0.0Mint a new coin GET /vault/1.0.0Get all coins mined so far GET /vault/1.0.0/ Get a specific coin GET /scoreboard/1.0.0Get the current scoreboard GET /scoreboard/1.0.0/ Get the score of a specific user

Coin Status Codes CodeDescription 0Pending validation 1Coin validated successfully (Yay!) 2Coin failed to validate (Back to the mines) Every RichCoin resource you obtain from the API has a “status” attribute. You can get a coin status of “2” due to many reasons. The exact reason is sent as an error code in the “reason” field (see next slide).

Error Codes Error CodeDescription clientTimestamp was unacceptable Solution was incorrect Solution was isomorphic to an existing solution Solution was malformed Provided coin ID was invalid Database error Unexpected runtime error. Last 2 are not your fault. Send us an if you ever see them.

Common Errors/Mistakes Calling APIs without subscribing or without the API key Sending the API key in a wrong format – Must be sent in the Authorization header prefixed by the string “Bearer ” (there should be a space between “Bearer” and the API key) Getting the production and sandbox keys mixed up

Common Errors/Mistakes Invalid clientTimestamp value in the request to mint coins – Must be a UTC timestamp (Milliseconds elapsed since Unix epoch) – Make sure your clock is synchronized against some well-known time service Exceeding your throttling limit (per-minute, per-API quota)

Known Issues Location header on the response to /vault/1.0.0 is wrong. We are working on getting a more static hostname for the service endpoint. – Until then some changes may occur – Do not hardcode the hostnames to your apps yet API Console feature in API store doesn’t work. If you see any other weirdness, let us know asap.

Application Development Best Practices Log all important events and API calls. – With timestamps Keep local copies of the RichCoins mined. – Make a copy of the solution matrix before submitting to the bank “In large distributed systems, component failures are the norm rather than the exception.” – GGL03

Sample Client App We implemented an interactive tool to invoke and test the APIs – Implemented in Python – Can use as an example on how to call the API programmatically Simply add your API key to settings.yaml and fire away

AWS for RichCoin CS290B – Spring 2014 Alex Pucher

AWS for RichCoin Single account per group – Only EC2 and S3 – Limited to USD per group – Using spot instances recommended You go over, you get nuked – You’ll get a warning (maybe) – Don’t store critical data on AWS

AWS for RichCoin You’ll receive: – Group account and password – AWS creds – EC2 Key pair – S3 bucket Must use your key pair and assigned bucket – Else, access is blocked

Disclaimers Policy enforcement questionable – Message if something doesn’t work but should – Stuff may disappear DO NOT store critical data on AWS

Questions?