API

This API tries to be RESTful and can be used programatically to create a bin and query it's contents to help your unit testing, your constant integration tests or your build server. It is designed to help people who are testing requests to an API that isn't under their control or for people who are adding webhooks to their product. It may have other uses too.

But before we talk about the real API, let's talk about the bin itself.

The Bin

As you already know, you can hit the https://www.postb.in/:binId endpoint to collect any kind of request data whether it is a GET, POST, PUT, PATCH, DELETE or whatever. This particular endpoint is not RESTful and is not part of this API. It isn't RESTful by definition. ie. it is meant to collect whatever you send to it.

You will receive a 200 and a RequestId as the body text. e.g. 'jEpYkw6a'. You may receive a 500 Internal Server Error is there is a problem.

Example

$ curl -v https://www.postb.in/YS4il4gS
> GET /YS4il4gS HTTP/1.1
> User-Agent: curl/7.35.0
> Host: localhost:8512
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: text/plain; charset=utf-8
< Content-Length: 9
< Date: Fri, 14 Aug 2015 11:46:28 GMT
<
YC61MdHw

The reqId here is YC61MdHw. You may use this code in the Get Request.

JSON Methods

This API tries to be RESTful. You may receive the following codes.

  • 200 OK - Request was successful. The data you received is what you asked for.
  • 201 Created - Object was created in response to a POST.

Bins

Create Bin

POST /api/bin

Creates a new bin and returns a binId and some other values to you. This bin is value for 30 mins after which time it will cease to exist and all operations on it will fail.

  • Method
    • POST
  • Params
    • [none]
  • Status Codes
    • 201 - with the result below
    • 500 - { "msg" : "Internal Server Error" }
  • Returns
    • binId - an opaque string to be used as the binId
    • now - the UTC timestamp (in ms) this bin was created
    • expires - the UTC timestamp (in ms) this bin will be deleted (approx. but not before)

Example

$ curl -v -X POST -d "" https://www.postb.in/api/bin
> POST /api/bin HTTP/1.1
> Accept: */*
>
< HTTP/1.1 201 Created
< Content-Type: application/json; charset=utf-8
< Content-Length: 85
< Date: Sun, 09 Aug 2015 10:10:20 GMT
<
{"binId":"YS4il4gS","now":1439113980530,"expires":1439115780530}

Get Bin

GET /api/bin/:binId

Returns information based on the binId you provide.

  • Method
    • GET
  • Params
    • binId - the binId of the one you wish to query
  • Status Codes
    • 404 - { "msg" : "No such bin" }
    • 500 - { "msg" : "Internal Server Error" }
  • Returns
    • (same as 'Create Bin')

Example

$ curl -v https://www.postb.in/api/bin/YS4il4gS
> GET /api/bin/YS4il4gS HTTP/1.1
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
< Content-Length: 85
< Date: Sun, 09 Aug 2015 10:14:34 GMT
<
{"binId":"YS4il4gS","now":1439113980530,"expires":1439115780530}

Delete Bin

DELETE /api/bin/:binId

Deletes this bin and all of it's posts. Note that if you try and delete a binId that doesn't exist, you'll still get a successful answer. i.e. a 200 (see below).

  • Method
    • DELETE
  • Params
    • binId - the binId of the one you wish to query
  • Status Codes
    • 200 - { "msg" : "Bin deleted" }
    • 500 - { "msg" : "Internal Server Error" }
  • Returns
    • { "msg" : "Bin deleted" }

Example

$ curl -v -X DELETE https://www.postb.in/api/bin/YS4il4gS
> DELETE /api/bin/YS4il4gS HTTP/1.1
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
< Content-Length: 85
< Date: Sun, 09 Aug 2015 10:14:34 GMT
<
{"msg":"Bin Deleted"}

Requests

Get Request

GET /api/bin/:binId/req/:reqId

Returns information based on the binId and reqId you provide.

  • Method
    • GET
  • Params
    • binId - the binId you wish to query, the opaque string received when the bin was created
    • reqId - the reqId you wish to query, the one returned to you when you hit the bin url to place requests in the bin
  • Status Codes
    • 200 - { ... req info ... }
    • 400 - { "msg" : "Invalid reqId. Provide a number." }
    • 400 - { "msg" : "Invalid reqId. Request number too high." }
    • 400 - { "msg" : "Invalid reqId. This older request has been deleted automatically." }
    • 404 - { "msg" : "Bin Does Not Exist" }
    • 500 - { "msg" : "Internal Server Error" }
  • Returns
    • See Example

Example

$ curl -v https://www.postb.in/api/bin/YS4il4gS/req/YC61MdHw
> GET /api/bin/YS4il4gS/req/YC61MdHw HTTP/1.1
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
< Content-Length: 85
< Date: Sun, 09 Aug 2015 10:14:34 GMT
<
{
  "method":"POST",
  "path":"/YS4il4gS",
  "headers":{"user-agent":"curl/7.35.0","host":"postb.in","accept":"*/*"},
  "query":{},
  "body":{},
  "ip":"1.2.3.4",
  "binId":"YS4il4gS",
  "inserted":1439468475026
}

Shift Request

GET /api/bin/:binId/req/shift

Removes the first element of the requests stored and returns it. This operation is useful since then you don't have to keep track of the reqIds if you know which order you made the requests in. This method changes the length of the array.

  • Method
    • GET
  • Params
    • binId - the binId you wish to query, the opaque string received when the bin was created
  • Status Codes
    • 200 - { ... req info ... }
    • 404 - { "msg" : "Bin Does Not Exist" }
    • 404 - { "msg" : "No requests in this bin" }
    • 500 - { "msg" : "Internal Server Error" }
  • Returns
    • See Example

Example

$ curl -v https://www.postb.in/api/bin/YS4il4gS/req/shift
> GET /api/bin/YS4il4gS/req/shift HTTP/1.1
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
< Content-Length: 85
< Date: Sun, 09 Aug 2015 10:14:34 GMT
<
{
  "method":"GET",
  "path":"/YS4il4gS",
  "headers":{"user-agent":"curl/7.35.0","host":"postb.in","accept":"*/*"},
  "query":{},
  "body":{},
  "ip":"1.2.3.4",
  "binId":"YS4il4gS",
  "inserted":1439468475026
}

Contents