The Setup

API

What do people use to get stuff done?

API

The Setup provides a very simple JSON-based API. I'd love to know if you do something interesting with it!

Methods

Interviews
Gear
Stats

Interviews

Getting a list

This method returns a basic list of all the interviews.

Requesting (GET):
/api/interviews

Will give you:

{
  "interviews": [
    {
      "slug": "fizban.the.fabulous",
      "name": "Fizban the Fabulous",
      "url": "http://usesthis.com/interviews/fizban.the.fabulous/",
      "summary": "Wizard",
      "date": 1425970800,
      "categories": [
        "mac",
        "wizard"
      ]
    },
    {
      "slug": "tasslehoff.burrfoot",
      "name": "Tasslehoff Burrfoot",
      "url": "http://usesthis.com/interviews/tasslehoff.burrfoot/",
      "summary": "Borrower",
      "date": 1425542400,
      "categories": [
        "linux",
        "thief"
      ]
    }
  ]
}
Getting an interview

This method returns a complete interview for the given slug, including gear.

Requesting (GET):
/api/interviews/{slug}

Will give you:

{
  "interview": {
    "slug": "tasslehoff.burrfoot",
    "name": "Tasslehoff Burrfoot",
    "url": "http://usesthis.com/interviews/tasslehoff.burrfoot/",
    "summary": "Borrower",
    "date": 1425542400,
    "categories": [
      "linux",
      "thief"
    ],
    "contents": "#### Who are you, and what do you do?...",
    "gear": {
      "hardware": [
        {
          "slug": "hoopak",
          "name": "Hoopak",
          "description": "A wooden staff with a sling.",
          "url": "http://www.hoopaks-r-us.com/"
        }
      ],
      "software": [
        {
          "slug": "wanderlust",
          "name": "Wanderlust",
          "description": "A need for travel.",
          "url": "http://my-kender.net/"
        }
      ]
    }
  }
}
Getting categories

This method returns a basic list of all the interview categories.

Requesting (GET):
/api/categories

Will give you:

{
  "categories": [
    "linux",
    "mac",
    "thief",
    "wizard"
  ]
}
Getting a category

This method returns a basic list of all the interviews for the given category.

Requesting (GET):
/api/categories/{slug}

Will give you:

{
  "interviews": [
    {
      "slug": "fizban.the.fabulous",
      "name": "Fizban the Fabulous",
      "url": "http://usesthis.com/interviews/fizban.the.fabulous/",
      "summary": "Wizard",
      "date": 1425970800,
      "categories": [
        "mac",
        "wizard"
      ]
    }
  ]
}

Gear

Getting a list

This method returns a basic list of all the hardware or software mentioned on the site. Note that these will be quite large.

Requesting (GET):
/api/hardware

Will give you:

{
  "gear": [
    {
      "slug": "hoopak",
      "name": "Hoopak"
    }
  ]
}

Requesting (GET):
/api/software

Will give you:

{
  "gear": [
    {
      "slug": "wanderlust",
      "name": "Wanderlust"
    }
  ]
}
Getting an item

This method returns a single piece of hardware or software for the given slug, including related interviews.

Requesting (GET):
/api/hardware/{slug}

Will give you:

{
  "gear": {
    "slug": "hoopak",
    "name": "Hoopak",
    "description": "A wooden staff with a sling.",
    "url": "http://www.hoopaks-r-us.com/",
    "interviews": [
      {
        "slug": "tasslehoff.burrfoot",
        "name": "Tasslehoff Burrfoot",
      }
    ]
  }
}

Requesting (GET):
/api/software/{slug}

Will give you:


{
  "gear": {
    "slug": "wanderlust",
    "name": "Wanderlust",
    "description": "A need for travel.",
    "url": "http://my-kender.net/"
    "interviews": [
      {
        "slug": "tasslehoff.burrfoot",
        "name": "Tasslehoff Burrfoot",
      }
    ]
  }
}

Stats

Getting general info

This method returns various site statistics, like the number of interviews.

Requesting (GET):
/api/stats

Will give you:

{
  "interviews": 2,
  "hardware": 10,
  "software": 3
}
Getting gear info

This method returns the top 50 hardware or software items mentioned on the site. You can also specify a given year by adding it to the URL.

Requesting (GET):
/api/stats/hardware

Will give you:

{
  "gear": [
    {
      "slug": "hoopak",
      "count": 1
    }
  ]
}

Requesting (GET):
/api/stats/software

Will give you:

{
  "gear": [
    {
      "slug": "wanderlust",
      "count": 1
    }
  ]
}

Changelog


  • Added details about the stats API endpoints, and added more examples to the existing docs.

  • Changed the URLs for the categories API to match the site (but the old ones will keep working forever).

  • Updated interviews to always have a gear element.

  • Added support for interview categories.

  • Initial public launch. Sorry about that.