public/api/v0/swagger.json
{
"swagger": "2.0",
"info": {
"title": "Micro-purchase API Documentation",
"description": "Endpoints for the micropurchase API",
"version": "0.0.1"
},
"schemes": [
"https"
],
"produces": [
"application\/json"
],
"basePath": "\/api\/v0",
"securityDefinitions": {
"api_key": {
"name": "HTTP_API_KEY",
"description": "Currently all authentication occurs via the GitHub API. Rather than having the micro-purchase platform generate and store API keys, GitHub Personal API Tokens act as the API key. If you have created an account on the micro-purchase platform, you are signed up to use the API. All you need to do is generate a [GitHub Personal API Token](https:\/\/github.com\/blog\/1509-personal-api-tokens) (with no scopes) and put it in the request headers.\n\n Note that many routes do not require any authentication at all. These docs will note the authentication options for each route.",
"type": "apiKey",
"in": "header"
}
},
"paths": {
"/auctions": {
"get": {
"summary": "List auctions",
"description": "Returns a list of all auctions (future, available, and closed). Each auction contains bids and each bid contains one bidder. If an auction is still running, `bid['bidder_id']` and all keys in `bidder` will be `null`. This request does not require authentication, but if you are authenticated, your bids will not be redacted. This is consistent with the behavior of the web UI.",
"security": [
{
"api_key": []
}
],
"responses": {
"200": {
"description": "Returns a list of auctions",
"schema": {
"$ref": "#\/definitions\/AuctionListResponse"
},
"examples": {
"application/json": {
"auctions": [
{
"issue_url": "https:\/\/github.com\/18F\/mpt3500\/issues\/10",
"github_repo": "https:\/\/github.com\/18F\/mpt3500",
"start_price": 3500,
"start_datetime": "2016-01-26T18:00:00+00:00",
"end_datetime": "2016-02-27T17:00:00+00:00",
"title": "Review a blog post",
"description": "Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur?\r\n\r\n## A Markdown Quote\r\n\r\n> Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur?\r\n\r\n```\r\ndef foo(bar)\r\n 10.times do\r\n puts bar\r\n end\r\nend\r\n```",
"id": 1,
"created_at": "2015-12-21T16:40:01+00:00",
"updated_at": "2015-12-21T16:40:01+00:00",
"summary": "## Summary\r\n\r\nWe need some prose to be proof-read.",
"bids": [
{
"bidder_id": null,
"auction_id": 1,
"amount": 222,
"created_at": "2016-01-06T16:59:59+00:00",
"updated_at": "2016-01-06T16:59:59+00:00",
"id": 68,
"bidder": {
"github_id": null,
"duns_number": null,
"name": null,
"email": null,
"sam_account": null,
"created_at": null,
"updated_at": null,
"id": null
}
},
{
"bidder_id": null,
"auction_id": 1,
"amount": 240,
"created_at": "2016-01-06T16:59:55+00:00",
"updated_at": "2016-01-06T16:59:55+00:00",
"id": 67,
"bidder": {
"github_id": null,
"duns_number": null,
"name": null,
"email": null,
"sam_account": null,
"created_at": null,
"updated_at": null,
"id": null
}
}
]
}
]
}
}
}
}
}
},
"/auctions/{id}": {
"get": {
"summary": "Show a specific auction",
"security": [
{
"api_key": []
}
],
"description": "This returns the details of a specific auction, in the same format as the auctions index",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the auction to retrieve",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Returns a single auction",
"schema": {
"$ref": "#\/definitions\/AuctionResponse"
}
},
"404": {
"description": "The auction is not found",
"schema": {
"$ref": "#\/definitions\/Error"
}
}
}
}
},
"/auctions/{id}/bids": {
"post": {
"consumes": [
"application\/json"
],
"security": [
{
"api_key": []
}
],
"summary": "Submit a Bid",
"description": "Submit a new bid to an auction via a JSON payload. Only integer bids are allowed and the bid may be rejected if it doesn't meet the validation rules for the auction. You must be authenticated and able to place a bid to use this method.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the auction you are bidding against",
"required": true,
"type": "integer"
},
{
"name": "body",
"description": "Bid payload",
"in": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"bid"
],
"properties": {
"bid": {
"type": "object",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "integer",
"minimum": 1
}
}
}
}
}
}
],
"responses": {
"200": {
"description": "Returns the bid object that was created",
"schema": {
"$ref": "#\/definitions\/BidResponse"
},
"examples": {
"application/json": {
"bid": {
"bidder_id": 1,
"auction_id": 3,
"amount": 1000,
"created_at": "2016-01-27T01:12:07+00:00",
"updated_at": "2016-01-27T01:12:07+00:00",
"id": 7,
"bidder": {
"github_id": "86790",
"duns_number": "123456789",
"name": "Alan deLevie",
"email": "",
"sam_account": true,
"created_at": "2015-12-23T14:51:34+00:00",
"updated_at": "2016-01-26T01:56:24+00:00",
"id": 1
}
}
}
}
},
"403": {
"description": "When the user is not authenticated",
"schema": {
"$ref": "#\/definitions\/Error"
}
},
"404": {
"description": "When the auction is not found",
"schema": {
"$ref": "#\/definitions\/Error"
}
}
}
}
},
"/admin/auctions": {
"get": {
"security": [
{
"api_key": []
}
],
"summary": "Administrator view of all auctions",
"description": "The administrator view of all auctions. This includes privileged information which is not shown to end users and requires administrator authentication.",
"responses": {
"200": {
"description": "Returns a list of auctions",
"schema": {
"$ref": "#\/definitions\/AdminAuctionListResponse"
}
},
"403": {
"description": "Returned if the user is not found or is not an admin",
"schema": {
"$ref": "#\/definitions\/Error"
}
}
}
}
},
"/admin/auctions/{id}": {
"get": {
"security": [
{
"api_key": []
}
],
"summary": "Administrator view of an auction. This includes privileged information which is not shown to end users and requires administrator authentication.",
"description": "The details of a specific auction. ",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the auction to retrieve",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Returns a single auction",
"schema": {
"$ref": "#\/definitions\/AdminAuctionResponse"
}
},
"403": {
"description": "Returned if the user is not found or not an admin",
"schema": {
"$ref": "#\/definitions\/Error"
}
},
"404": {
"description": "If the auction is not found",
"schema": {
"$ref": "#\/definitions\/Error"
}
}
}
}
},
"/admin/users": {
"get": {
"security": [
{
"api_key": []
}
],
"summary": "Administrator view of all users",
"description": "The administrator view of all users. This includes privileged information which is not shown to end users and requires administrator authentication.",
"responses": {
"200": {
"description": "Returns lists of users and metadata",
"schema": {
"$ref": "#\/definitions\/AdminReport"
}
},
"403": {
"description": "Returned if the user is not found or not an admin",
"schema": {
"$ref": "#\/definitions\/Error"
}
}
}
}
}
},
"definitions": {
"Auction": {
"title": "Auction",
"description": "The public representation of a single auction",
"type": "object",
"required": [
"id",
"title",
"summary",
"description",
"customer",
"issue_url",
"github_repo",
"start_price",
"started_at",
"ended_at",
"created_at",
"updated_at",
"bids",
"skills",
"type"
],
"properties": {
"id": {
"title": "Auction ID",
"description": "A unique identifier for the auction",
"type": "integer",
"example": 1
},
"title": {
"title": "Auction Title",
"example": "Auction title",
"type": "string"
},
"summary": {
"type": "string",
"title": "Summary",
"description": "A markdown-formatted summary of the auction",
"example": "The first part of the auction description"
},
"description": {
"type": "string",
"title": "Description",
"description": "A markdown-formatted description of the auction. This is usually a continuation from the first paragraph of the summary.",
"example": "The rest of the auction description"
},
"type": {
"type": "string",
"title": "Auction type",
"enum": ["reverse", "sealed_bid"]
},
"issue_url": {
"title": "GitHub Issue URL",
"description": "A corresponding GitHub issue for the auction",
"type": "string",
"format": "url",
"example": "https://github.com/18F/micropurchase/issues/217"
},
"github_repo": {
"title": "GitHub Repository",
"description": "The GitHub repository where the auction pull request should be opened against",
"type": "string",
"format": "url",
"example": "https://github.com/18f/micropurchase",
"x-comment": "Where the auction pull request should be opened against"
},
"start_price": {
"type": "integer",
"title": "Start Price",
"description": "The starting price of the auction. This is the exclusive ceiling of all bids. For sealed-bid auctions, the highest allowed bid is the starting price minus $1. For open reverse auctions, bidding starts at this amount, but any new bid must be lower than the previous lowest bid.",
"example": 3500,
"minimum": 1
},
"customer": {
"title": "Customer",
"description": "The name of the agency requesting the auction.",
"example": "18F",
"type": ["string", "null"]
},
"started_at": {
"title": "Start Time",
"description": "When the auction is open for bidding.",
"type": "string",
"format": "date-time"
},
"ended_at": {
"title": "End Time",
"description": "The date-time the auction is closed and the winning bid is determined.",
"type": "string",
"format": "date-time"
},
"created_at": {
"title": "Creation Time",
"description": "When the auction record was created in the database",
"type": "string",
"format": "date-time"
},
"updated_at": {
"title": "Modification Time",
"description": "When the auction record was last updated",
"type": "string",
"format": "date-time"
},
"winning_bid": {
"$ref": "#\/definitions\/WinningBid"
},
"bids": {
"type": "array",
"items": {
"$ref": "#\/definitions\/Bid"
}
},
"skills": {
"type": "array",
"example": ["rspec", "ruby on rails"],
"items": {
"type": "string"
}
}
}
},
"WinningBid": {
"description": "The current winning bid for the auction. For open reverse auctions, these fields will provide information about the current lowest bid during the auction. The bidder ID is provided as a convenient way for your program to check if the winning bid is yours. For sealed-bid auctions, these values will be nil until the auction is over and the final winning bid has been determined. If there is no bid, these fields will be nil.",
"type": "object",
"required": [
"amount",
"bidder_id"
],
"properties": {
"amount": {
"title": "Amount",
"type": [
"integer",
"null"
]
},
"bidder_id": {
"title": "Bidder ID",
"example": 34,
"type": [
"integer",
"null"
]
}
}
},
"Bid": {
"title": "Bid",
"description": "The public representation of a single bid. Note that in some cases -- for instance, when a reverse auction is still running -- information in the auctions may be redacted with nil",
"type": "object",
"required": [
"bidder_id",
"auction_id",
"amount",
"created_at",
"updated_at",
"id",
"bidder"
],
"properties": {
"id": {
"title": "Bid ID",
"description": "A unique identifier for the bid",
"type": "integer"
},
"bidder_id": {
"title": "Bidder ID",
"example": 45,
"type": [
"integer",
"null"
]
},
"auction_id": {
"title": "Auction ID",
"description": "The ID of the related auction",
"example": 1,
"type": "integer"
},
"amount": {
"title": "Amount",
"description": "The amount of the bid in dollars.",
"type": "integer",
"example": 2300,
"minimum": 0,
"exclusiveMinimum": true
},
"created_at": {
"title": "Bid Creation Time",
"description": "The datetime of when the bid was submitted",
"type": "string",
"format": "date-time"
},
"updated_at": {
"title": "Bid Update Time",
"description": "Since bids are not updated after being posted, same as creation time",
"type": "string",
"format": "date-time"
},
"bidder": {
"$ref": "#\/definitions\/Bidder"
}
}
},
"Bidder": {
"title": "Bidder",
"description": "The public information for a specific bidder. Note that in some cases -- for instance, when a reverse auction is still running -- all information about bidders who are not the authenticated user will be redacted and replaced with `nil` values.",
"type": "object",
"required": [
"id",
"duns_number",
"name",
"github_id",
"github_login",
"sam_status",
"created_at",
"updated_at"
],
"properties": {
"id": {
"title": "Bidder ID",
"example": 34,
"type": [
"integer",
"null"
]
},
"github_id": {
"title": "GitHub ID",
"description": "The bidder's ID on GitHub",
"example": 3402,
"type": [
"string",
"null"
]
},
"duns_number": {
"title": "DUNS Number",
"format": "duns",
"type": [
"string",
"null"
]
},
"name": {
"title": "Name",
"example": "Micah Purchase",
"type": [
"string",
"null"
]
},
"github_login": {
"title": "GitHub Username",
"example": "github_login",
"type": [
"string",
"null"
]
},
"sam_status": {
"title": "SAM.gov Status",
"example": "sam_accepted",
"type": [
"string",
"null"
]
},
"created_at": {
"title": "Account Creation Time",
"format": "date-time",
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"title": "Account Modification Time",
"description": "When the bidder's account information was last updated, either as a result of the user editing it or automated processes like SAM validation.",
"format": "date-time",
"type": [
"string",
"null"
],
"format": "date-time"
}
}
},
"AuctionResponse": {
"title": "Auction response",
"description": "The API currently returns a wrapper around a single auction in its response",
"type": "object",
"required": [
"auction"
],
"properties": {
"auction": {
"$ref": "#\/definitions\/Auction"
}
}
},
"AuctionListResponse": {
"title": "Auction list response",
"description": "This response contains an array of one or more auctions",
"type": "object",
"required": [
"auctions"
],
"properties": {
"auctions": {
"type": "array",
"uniqueItems": true,
"items": {
"$ref": "#\/definitions\/Auction"
}
}
}
},
"BidResponse": {
"title": "Bid Response",
"description": "Returned as a response to submitting a bid",
"type": "object",
"required": [
"bid"
],
"properties": {
"bid": {
"$ref": "#\/definitions\/Bid"
}
}
},
"AdminAuction": {
"title": "Admin Auction",
"description": "The admin view of a single auction. This includes all of the fields in the regular `Auction` class as well as some additional privileged fields",
"allOf": [
{
"$ref": "#\/definitions\/Auction"
},
{
"type": "object",
"required": [
"billable_to",
"c2_proposal_url",
"notes",
"delivery_due_at",
"delivery_url",
"paid_at"
],
"properties": {
"billable_to": {
"title": "Billable To",
"description": "The Tock code that the auction should be billable to",
"type": [
"string",
"null"
]
},
"c2_proposal_url": {
"title": "C2 Proposal URL",
"description": "The URL for the project's purchase request in C2",
"format": "url",
"type": [
"string",
"null"
]
},
"notes": {
"title": "Notes",
"description": "Private notes for the auction",
"type": [
"string",
"null"
]
},
"delivery_due_at": {
"title": "Delivery Due At",
"description": "The time that delivery is due by.",
"format": "date-time",
"type": [
"string",
"null"
]
},
"delivery_url": {
"title": "Payment delivery URL",
"description": "A URL where the vendor can accept a P-card purchase",
"format": "url",
"type": [
"string",
"null"
]
},
"paid_at": {
"title": "Paid At",
"description": "The time the vendor was paid for the work. The presence of this field can also be used as a boolean that the vendor has been paid.",
"format": "date-time",
"type": [
"string",
"null"
]
}
}
}
]
},
"AdminAuctionResponse": {
"title": "Admin Auction Response",
"description": "The response for requesting a single auction via the admin API",
"type": "object",
"required": [
"auction"
],
"properties": {
"auction": {
"$ref": "#\/definitions\/Auction"
}
}
},
"AdminAuctionListResponse": {
"title": "Admin Auction List Response",
"description": "The response for requesting admin auctions",
"type": "object",
"required": [
"auctions"
],
"properties": {
"auctions": {
"type": "array",
"uniqueItems": true,
"items": {
"$ref": "#\/definitions\/Auction"
}
}
}
},
"AdminReport": {
"type": "object",
"required": [
"admin_report"
],
"properties": {
"admin_report": {
"$ref": "#\/definitions\/AdminUserInfo"
}
}
},
"AdminUserInfo": {
"title": "Admin User Info",
"description": "Metadata about users",
"type": "object",
"required": [
"quick_stats",
"non_admin_users",
"admin_users"
],
"properties": {
"quick_stats": {
"$ref": "#\/definitions/QuickStats"
},
"non_admin_users": {
"title": "Non-admin Users",
"description": "An array of all the system's users",
"type": "array",
"uniqueItems": true,
"items": {
"$ref": "#\/definitions\/User"
}
},
"admin_users": {
"title": "Admin Users",
"description": "An array of all the admin users",
"type": "array",
"uniqueItems": true,
"items": {
"$ref": "#\/definitions\/User"
}
}
}
},
"QuickStats": {
"type": "object",
"properties": {
"total_users": {
"title": "Total Users",
"description": "The total users in the system",
"type": "integer",
"minimum": 0,
"example": 87
},
"users_with_duns": {
"title": "Users with DUNS Numbers",
"type": "integer",
"minimum": 0,
"example": 23
},
"users_in_sam": {
"title": "Users in SAM.gov",
"type": "integer",
"minimum": 0,
"example": 21
},
"notes": {
"title": "Notes",
"description": "Used for storing some notes about users",
"type": "string"
}
},
"required": [
"total_users",
"users_with_duns",
"users_in_sam",
"notes"
]
},
"User": {
"title": "User",
"description": "The admin information about a user",
"type": "object",
"required": [
"id",
"github_id",
"duns_number",
"name",
"created_at",
"updated_at",
"email",
"sam_status",
"payment_url",
"github_login",
"contracting_officer",
"small_business"
],
"properties": {
"id": {
"title": "User ID",
"description": "The unique record ID for the user",
"type": "integer"
},
"github_id": {
"title": "Github ID",
"description": "The ID for the user on the GitHub",
"example": 34001,
"type": [
"string",
"null"
]
},
"contracting_officer": {
"title": "Contracting Officer?",
"description": "Returns true if the user is a contracting officer. Only admins can be contracting officers.",
"type": "boolean"
},
"small_business": {
"title": "Small Business?",
"description": "Returns true if the user is a small business. This field is only relevant for regular users.",
"type": "boolean"
},
"duns_number": {
"title": "DUNS Number",
"description": "The DUNS number for the user",
"type": "string",
"format": "duns"
},
"name": {
"title": "Name",
"description": "The user's name",
"example": "Micah Purchase",
"type": "string"
},
"created_at": {
"title": "Created At",
"description": "When the user's account was created",
"format": "date-time",
"type": "string"
},
"updated_at": {
"title": "Updated At",
"description": "When the user record was last modified.",
"format": "date-time",
"type": "string"
},
"email": {
"title": "Email Address",
"description": "The user's email address",
"type": "string",
"format": "email"
},
"sam_status": {
"title": "SAM Status",
"description": "The status of the user in SAM.gov. This will be pending until the user is found and validated. Only accepted users can bid.",
"type": "string",
"enum": ["duns_blank", "sam_accepted", "sam_rejected", "sam_pending"]
},
"payment_url": {
"title": "Payment URL",
"description": "A URL where the vendor can accept payment after successfully delivering an auction.",
"format": "url",
"type": [
"string",
"null"
]
},
"github_login": {
"title": "GitHub Login",
"description": "The username on GitHub for the user.",
"type": [
"string",
"null"
]
}
}
},
"Error": {
"title": "Error",
"description": "The standard format for error messages",
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"title": "Error Message",
"example": "You must be authenticated to bid on an auction",
"type": "string"
}
}
}
}
}