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
Queue
Web Server
Coin
Validator
Client
(You)
Database
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 e-mail to hiranya@cs.ucsb.edu
• 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…
• https://euca-128-111-179-147.eucalyptus.race.cs.ucsb.edu:9443/carbon
• Login using the username and password sent in the
email.
• 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…
• https://euca-128-111-179-147.eucalyptus.race.cs.ucsb.edu:9443/store/
• 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 <Your-API-Key>
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”: “100000011000100”,
“clientTimestamp”: 123456
}
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/<Unique-ID>
{
“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 Call
Description
POST /vault/1.0.0
Mint a new coin
GET /vault/1.0.0
Get all coins mined so far
GET /vault/1.0.0/<coinId>
Get a specific coin
GET /scoreboard/1.0.0
Get the current scoreboard
GET /scoreboard/1.0.0/<username>
Get the score of a specific user
Coin Status Codes
Code
Description
0
Pending validation
1
Coin validated successfully (Yay!)
2
Coin 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 Code
Description
100100
clientTimestamp was unacceptable.
100101
Solution was incorrect.
100102
Solution was isomorphic to an existing
solution.
100103
Solution was malformed.
100104
Provided coin ID was invalid.
200100
Database error.
200101
Unexpected runtime error.
• Last 2 are not your fault. Send us an e-mail 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 100.0 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
• https://richcoin.signin.aws.amazon.com/
Questions?