Reverse 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: 231
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": "reverse"
  }
}


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

{
  "data": {
    "status": "active.tendering",
    "title": "casings for state awards",
    "dateModified": "2019-11-11T14:39:25.970194+02:00",
    "owner": "broker",
    "items": [
      {
        "id": "631da61b93484a159d3a3f57006355cb",
        "description": "casings for state awards",
        "quantity": 5
      }
    ],
    "auctionPeriod": {
      "shouldStartAfter": "2019-11-11T14:44:25.962474+02:00"
    },
    "tenderPeriod": {
      "startDate": "2019-11-11T14:39:25.962474+02:00",
      "endDate": "2019-11-11T14:44:25.962474+02:00"
    },
    "value": {
      "amount": 500.0,
      "currency": "USD"
    },
    "minimalStep": {
      "amount": 35,
      "currency": "USD"
    },
    "procurementMethodType": "reverse",
    "id": "2bea4409cf9749809922abb5e4974f17",
    "numberOfBids": 0,
    "next_check": "2019-11-11T14:44:25.962474+02:00",
    "auctionID": "broker: casings for state awards",
    "auctionUrl": "http://auction.localhost/reverse-auctions/2bea4409cf9749809922abb5e4974f17"
  },
  "access": {
    "token": "423223d1be57489eb91edea360571dd6"
  }
}

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/2bea4409cf9749809922abb5e4974f17 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:25.970194+02:00",
    "items": [
      {
        "id": "631da61b93484a159d3a3f57006355cb",
        "description": "casings for state awards",
        "quantity": 5
      }
    ],
    "auctionPeriod": {
      "shouldStartAfter": "2019-11-11T14:44:25.962474+02:00"
    },
    "tenderPeriod": {
      "startDate": "2019-11-11T14:39:25.962474+02:00",
      "endDate": "2019-11-11T14:44:25.962474+02:00"
    },
    "value": {
      "amount": 500.0,
      "currency": "USD"
    },
    "minimalStep": {
      "amount": 35,
      "currency": "USD"
    },
    "procurementMethodType": "reverse",
    "id": "2bea4409cf9749809922abb5e4974f17",
    "auctionID": "broker: casings for state awards",
    "auctionUrl": "http://auction.localhost/reverse-auctions/2bea4409cf9749809922abb5e4974f17"
  }
}

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": "2bea4409cf9749809922abb5e4974f17",
      "dateModified": "2019-11-11T14:39:25.970194+02:00"
    }
  ],
  "next_page": {
    "offset": "2019-11-11T14:39:25.970194+02:00",
    "path": "/api/2.4/auctions?offset=2019-11-11T14%3A39%3A25.970194%2B02%3A00",
    "uri": "http://api.atreus.auction/api/2.4/auctions?offset=2019-11-11T14%3A39%3A25.970194%2B02%3A00"
  }
}

Creating bid

During auction.tenderPeriod it is allowed to register bids.

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

{
  "data": {
    "tenderers": [
      {
        "name": "State Management of Affairs"
      }
    ],
    "value": {
      "amount": 500
    }
  }
}


201 Created
Content-Type: application/json
Location: http://api.atreus.auction/api/2.4/auctions/2bea4409cf9749809922abb5e4974f17/bids/cb58b44365194be797cf05339f79607b
X-Content-Type-Options: nosniff

{
  "data": {
    "date": "2019-11-11T14:39:26.002297+02:00",
    "id": "cb58b44365194be797cf05339f79607b",
    "status": "active",
    "owner": "broker",
    "tenderers": [
      {
        "name": "State Management of Affairs"
      }
    ],
    "value": {
      "amount": 500.0,
      "currency": "USD"
    },
    "participationUrl": "http://auction.localhost/reverse-auctions/2bea4409cf9749809922abb5e4974f17/login?bidder_id=cb58b44365194be797cf05339f79607b&signature=36237zfupn/LFtZpW7/vNVDz81VIzKOpRhKKHkXecfx7y8OOO1PeD2rsBMF6vfeQOpvk625MjjMgI9%2BnH0ikAQ%3D%3D"
  },
  "access": {
    "token": "c92f9eb864f54ba9a82e4dd14c53310d"
  }
}

Switching to auction.active

Getting auction URL

Anyone can access auction by Auction.auctionUrl:

GET /api/2.4/auctions/2bea4409cf9749809922abb5e4974f17 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.047799+02:00",
    "items": [
      {
        "id": "631da61b93484a159d3a3f57006355cb",
        "description": "casings for state awards",
        "quantity": 5
      }
    ],
    "auctionPeriod": {
      "startDate": "2019-11-11T14:39:26.025666+02:00",
      "shouldStartAfter": "2019-11-11T14:39:26.025666+02:00"
    },
    "tenderPeriod": {
      "startDate": "2019-11-09T14:39:26.025666+02:00",
      "endDate": "2019-11-11T14:39:26.025666+02:00"
    },
    "value": {
      "amount": 500.0,
      "currency": "USD"
    },
    "minimalStep": {
      "amount": 35,
      "currency": "USD"
    },
    "procurementMethodType": "reverse",
    "id": "2bea4409cf9749809922abb5e4974f17",
    "auctionID": "broker: casings for state awards",
    "auctionUrl": "http://auction.localhost/reverse-auctions/2bea4409cf9749809922abb5e4974f17"
  }
}

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/2bea4409cf9749809922abb5e4974f17 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.075962+02:00",
    "items": [
      {
        "id": "631da61b93484a159d3a3f57006355cb",
        "description": "casings for state awards",
        "quantity": 5
      }
    ],
    "auctionPeriod": {
      "startDate": "2019-11-11T14:39:26.025666+02:00",
      "endDate": "2019-11-11T14:39:26.073479+02:00"
    },
    "tenderPeriod": {
      "startDate": "2019-11-09T14:39:26.025666+02:00",
      "endDate": "2019-11-11T14:39:26.025666+02:00"
    },
    "value": {
      "amount": 500.0,
      "currency": "USD"
    },
    "minimalStep": {
      "amount": 35,
      "currency": "USD"
    },
    "procurementMethodType": "reverse",
    "id": "2bea4409cf9749809922abb5e4974f17",
    "auctionID": "broker: casings for state awards",
    "auctionUrl": "http://auction.localhost/reverse-auctions/2bea4409cf9749809922abb5e4974f17"
  }
}

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