Texas Auctions Tutorial

Exploring basic rules

Let’s try exploring the /auctions endpoint:

GET /api/2.4/auctions HTTP/1.0
Authorization: Basic YnJva2VyOg==
Host: api.atreus.auction


200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff

{
  "data": [],
  "next_page": {
    "offset": "",
    "path": "/api/2.4/auctions?offset=",
    "uri": "http://api.atreus.auction/api/2.4/auctions?offset="
  }
}

Just invoking it reveals an empty set.

Creating auction

Let’s create auction with minimal amount of data (only required parameters):

POST /api/2.4/auctions HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 229
Content-Type: application/json
Host: api.atreus.auction

{
  "data": {
    "title": "casings for state awards",
    "value": {
      "amount": 500
    },
    "minimalStep": {
      "amount": 35
    },
    "items": [
      {
        "description": "casings for state awards",
        "quantity": 5
      }
    ],
    "tenderPeriod": {},
    "procurementMethodType": "texas"
  }
}


201 Created
Content-Type: application/json
Location: http://api.atreus.auction/api/2.4/auctions/63b7197175374c00ae8e6d26c5886fb5
X-Content-Type-Options: nosniff

{
  "data": {
    "status": "active.tendering",
    "title": "casings for state awards",
    "dateModified": "2019-11-11T14:39:26.373496+02:00",
    "owner": "broker",
    "items": [
      {
        "id": "c2cbde9fefa24cd6b92fdb1572c717d6",
        "description": "casings for state awards",
        "quantity": 5
      }
    ],
    "auctionPeriod": {
      "shouldStartAfter": "2019-11-11T14:44:26.369624+02:00"
    },
    "tenderPeriod": {
      "startDate": "2019-11-11T14:39:26.369624+02:00",
      "endDate": "2019-11-11T14:44:26.369624+02:00"
    },
    "value": {
      "amount": 500.0,
      "currency": "USD"
    },
    "minimalStep": {
      "amount": 35,
      "currency": "USD"
    },
    "procurementMethodType": "texas",
    "id": "63b7197175374c00ae8e6d26c5886fb5",
    "numberOfBids": 0,
    "next_check": "2019-11-11T14:44:26.369624+02:00",
    "auctionID": "broker: casings for state awards",
    "auctionUrl": "http://auction.localhost/texas-auctions/63b7197175374c00ae8e6d26c5886fb5"
  },
  "access": {
    "token": "684216fc7a7244219bdcbe4fe723198b"
  }
}

Success! Now we can see a new auction was created. Response header Location shows it’s location. Response body provides information on the created auction, his inner ID (that matches the Location segment) and his official auctionID. Take a look at procurementMethodType and the fact that auction is in the active.tendering status.

Getting auction

Let’s access the URL of the created object (the Location header of the response):

GET /api/2.4/auctions/63b7197175374c00ae8e6d26c5886fb5?acc_token=684216fc7a7244219bdcbe4fe723198b HTTP/1.0
Authorization: Basic YnJva2VyOg==
Host: api.atreus.auction


200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff

{
  "data": {
    "status": "active.tendering",
    "title": "casings for state awards",
    "dateModified": "2019-11-11T14:39:26.373496+02:00",
    "owner": "broker",
    "items": [
      {
        "id": "c2cbde9fefa24cd6b92fdb1572c717d6",
        "description": "casings for state awards",
        "quantity": 5
      }
    ],
    "auctionPeriod": {
      "shouldStartAfter": "2019-11-11T14:44:26.369624+02:00"
    },
    "tenderPeriod": {
      "startDate": "2019-11-11T14:39:26.369624+02:00",
      "endDate": "2019-11-11T14:44:26.369624+02:00"
    },
    "value": {
      "amount": 500.0,
      "currency": "USD"
    },
    "minimalStep": {
      "amount": 35,
      "currency": "USD"
    },
    "procurementMethodType": "texas",
    "id": "63b7197175374c00ae8e6d26c5886fb5",
    "numberOfBids": 0,
    "next_check": "2019-11-11T14:44:26.369624+02:00",
    "auctionID": "broker: casings for state awards",
    "auctionUrl": "http://auction.localhost/texas-auctions/63b7197175374c00ae8e6d26c5886fb5"
  }
}

We can see the same response we got after creating auction. Let’s see what listing of auctions reveals us:

GET /api/2.4/auctions HTTP/1.0
Authorization: Basic YnJva2VyOg==
Host: api.atreus.auction


200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff

{
  "data": [
    {
      "id": "63b7197175374c00ae8e6d26c5886fb5",
      "dateModified": "2019-11-11T14:39:26.373496+02:00"
    }
  ],
  "next_page": {
    "offset": "2019-11-11T14:39:26.373496+02:00",
    "path": "/api/2.4/auctions?offset=2019-11-11T14%3A39%3A26.373496%2B02%3A00",
    "uri": "http://api.atreus.auction/api/2.4/auctions?offset=2019-11-11T14%3A39%3A26.373496%2B02%3A00"
  }
}

Creating bid

During auction.tenderPeriod it is allowed to register bids.

POST /api/2.4/auctions/63b7197175374c00ae8e6d26c5886fb5/bids HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 66
Content-Type: application/json
Host: api.atreus.auction

{
  "data": {
    "tenderers": [
      {
        "name": "State Management of Affairs"
      }
    ]
  }
}


201 Created
Content-Type: application/json
Location: http://api.atreus.auction/api/2.4/auctions/63b7197175374c00ae8e6d26c5886fb5/bids/b38847e1355c420aafe7093b736b7b94
X-Content-Type-Options: nosniff

{
  "data": {
    "date": "2019-11-11T14:39:26.402344+02:00",
    "id": "b38847e1355c420aafe7093b736b7b94",
    "status": "active",
    "owner": "broker",
    "tenderers": [
      {
        "name": "State Management of Affairs"
      }
    ],
    "value": {
      "currency": "USD",
      "amount": 500.0
    },
    "participationUrl": "http://auction.localhost/texas-auctions/63b7197175374c00ae8e6d26c5886fb5/login?bidder_id=b38847e1355c420aafe7093b736b7b94&signature=xIUSLH9US7yT1uaqPkL5DD3ziE8vaoNVCLsyQUznjI3fftwqOVkzTk03H1PK6T/Rphk5FSQG2I%2Bik19dsNVkAQ%3D%3D"
  },
  "access": {
    "token": "3d6b0b794e174d3ab75f823768abb766"
  }
}

Switching to auction.active

Getting auction URL

Anyone can access auction by Auction.auctionUrl:

GET /api/2.4/auctions/63b7197175374c00ae8e6d26c5886fb5 HTTP/1.0
Authorization: Basic YW55b25lOg==
Host: api.atreus.auction


200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff

{
  "data": {
    "status": "active.auction",
    "title": "casings for state awards",
    "dateModified": "2019-11-11T14:39:26.446281+02:00",
    "items": [
      {
        "id": "c2cbde9fefa24cd6b92fdb1572c717d6",
        "description": "casings for state awards",
        "quantity": 5
      }
    ],
    "auctionPeriod": {
      "startDate": "2019-11-11T14:39:26.424016+02:00",
      "shouldStartAfter": "2019-11-11T14:39:26.424016+02:00"
    },
    "tenderPeriod": {
      "startDate": "2019-11-09T14:39:26.424016+02:00",
      "endDate": "2019-11-11T14:39:26.424016+02:00"
    },
    "value": {
      "amount": 500.0,
      "currency": "USD"
    },
    "minimalStep": {
      "amount": 35,
      "currency": "USD"
    },
    "procurementMethodType": "texas",
    "id": "63b7197175374c00ae8e6d26c5886fb5",
    "auctionID": "broker: casings for state awards",
    "auctionUrl": "http://auction.localhost/texas-auctions/63b7197175374c00ae8e6d26c5886fb5"
  }
}

Getting bid URL

Bidders can find out their participation URLs via their bids:

See the bid.participationUrl in the response.

Auction complete

GET /api/2.4/auctions/63b7197175374c00ae8e6d26c5886fb5 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Host: api.atreus.auction


200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff

{
  "data": {
    "status": "complete",
    "title": "casings for state awards",
    "dateModified": "2019-11-11T14:39:26.473611+02:00",
    "items": [
      {
        "id": "c2cbde9fefa24cd6b92fdb1572c717d6",
        "description": "casings for state awards",
        "quantity": 5
      }
    ],
    "auctionPeriod": {
      "startDate": "2019-11-11T14:39:26.424016+02:00",
      "endDate": "2019-11-11T14:39:26.470844+02:00"
    },
    "tenderPeriod": {
      "startDate": "2019-11-09T14:39:26.424016+02:00",
      "endDate": "2019-11-11T14:39:26.424016+02:00"
    },
    "value": {
      "amount": 500.0,
      "currency": "USD"
    },
    "minimalStep": {
      "amount": 35,
      "currency": "USD"
    },
    "procurementMethodType": "texas",
    "id": "63b7197175374c00ae8e6d26c5886fb5",
    "auctionID": "broker: casings for state awards",
    "auctionUrl": "http://auction.localhost/texas-auctions/63b7197175374c00ae8e6d26c5886fb5"
  }
}

We can see the result we got after completion of the auction.