Reqres – Test your front-end against a real API

reqres

Reqres simulates real application scenarios. If you want to test a user authentication system, Reqres will respond to a successful login/register request with a token for you to identify a sample user, or with a 403 forbidden response to an unsuccessful login/registration attempt.

Great to see an initiative like this. Nearly three years ago I created a simple Movies Database API exactly for this very reason: I wanted to make an API frontend consumer based on a proper API. Now I that look back at it we’ve come a long way: people have come to understand that it takes more than just changing the response to JSON in order to make an API RESTful.

Reqres – A hosted REST-API ready to respond to your AJAX requests →

Slate – Beautiful static documentation for your API

slate-api-documentation

Slate helps you create beautiful API documentation. Think of it as an intelligent, responsive documentation template for your API.

Slate – Beautiful static documentation for your API →
Tutorial: Writing API Documentation with Slate →

Related: Swagger, a dynamic documentation generator

Swagger

swagger-hero

Speaking of APIs and documentation in the previous post:

Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services.

Describe your API in a JSON file like this, and Swagger will turn it into that. Alternatively you can provide your project with Swagger Annotations and then run it through a parser (such as Swagger-PHP) to let it automatically generate the docs.

Swagger →
Swagger-PHP →

Related: Simple REST API Explorer, my attempt to quickly allow one to consume a RESTful/Hypermedia API.

Your API Consumers Aren’t Who You Think They Are

Traditionally, you’d expect most inquiries about APIs to be very technical: How can I upload bulk attachments with multipart POST bodies? Increasingly, questions are becoming more like amateur Stack Overflow questions: How do I hook the Microsoft Access into the REST?

The users behind such questions aren’t tech-illiterate, they simply have no idea how to code and aren’t familiar with the lingo. They don’t really know where to start, but they want to know about your API.

This is awesome.

Contains a few practical tips on how to lower the barrier to consuming your API.

Your API Consumers Aren’t Who You Think They Are →

(via Johan)

DocJSON – JSON HyperMedia Documents

docjson

A DocJSON document consists of standard JSON with the addition of a set of hypermedia controls that are used to express the actions that may be taken. DocJSON is a flexible document format that does not impose any structural restrictions either on the data representation style or on the layout of hypermedia controls used within the document.

The true power of the spec lies in restrictions it oposes:

A document may be any valid JSON with the single restriction that the object key "_type" is reserved.

Real genius imho, as it allows the implementer to use any specific structure he wants instead of imposing a structure as other formats such as Collection+JSON, Siren, Hal, JSON-LD, etc. do.

If for one always inject the returned HTTP status code as a status object into the response (example). With DocJSON I’m allowed to do so, plus I can make my API discoverable by consumers who have no prior knowledge of the keys it holds.

Linking back to some HyperMedia things I’ve been tinkering about myself this might actually formulate the answer to the problem I had: wanting to roll my own structure without needing to register a new format (which one shouldn’t).

Looking forward to how this spec will evolve 🙂

DocJSON →

Related: JSON API →

JSON API

{
  "links": {
    "posts.author": {
      "href": "http://example.com/people/{posts.author}",
      "type": "people"
    },
    "posts.comments": {
      "href": "http://example.com/comments/{posts.comments}",
      "type": "comments"
    }
  }
  "posts": [{
    "id": "1",
    "title": "Rails is Omakase",
    "links": {
      "author": "9",
      "comments": [ "1", "2", "3" ]
   }, {
    "id": "2",
    "title": "The Parley Letter",
    "links": {
      "author": "9",
      "comments": [ "4", "5" ]
   }, {
    "id": "1",
    "title": "Dependency Injection is Not a Virtue",
    "links": {
      "author": "9",
      "comments": [ "6" ]
    }
  }],
  "people": [{
    "id": "9",
    "name": "@d2h"
  }],
  "comments": [{
    "id": "1",
    "body": "Mmmmmakase"
  }, {
    "id": "2",
    "body": "I prefer unagi"
  }, {
    "id": "3",
    "body": "What's Omakase?"
  }, {
    "id": "4",
    "body": "Parley is a discussion, especially one between enemies"
  }, {
    "id": "5",
    "body": "The parsley letter"
  }, {
    "id": "6",
    "body": "Dependency Injection is Not a Vice"
  }]
}

“JSON API” is a JSON-based read/write hypermedia-type designed to support a smart client who wishes build a data-store of information.

Good to see this formalised, as JSON on its own is not Hypermedia. Mime-type to be is application/vnd.api+json (pending).

On the other hand I’ve been pondering about tolerating JSON based APIs that return structured JSON (making it “RMM Level 2.5”) as plain JSON (application/json). Take my own Movies DB API for example: it’s all structured and could be RMM Level 3 (and thus be a genuine Hypermedia API) if it wouldn’t be served as application/json, but with a mime-type I’d have to regiser at IANA … but registering one would just loiter the standards space, make it an unwanted option — XKCD nailed the reasoning behind this perfectly

JSON API →

Not sure what a RESTful/Hypermedia API is? Then check out my course materials on the subject: RESTful APIs →

pytesla — Python bindings to the Tesla Model S REST API

tesla-model-s-side-small

pytesla is a python binding to the Tesla Model S REST API so that you can monitor your car or programmatically interact with it. It makes it easy to schedule charging times, trigger heating/cooling according to weather or just gather stats.

A car with an API, how cool is that? Can’t wait for the day that an exploit is found in this. Also: that API ain’t RESTful

pytesla →
Tesla Model S REST API →

(via Teusje)

Guzzle — PHP HTTP Client

Guzzle is a framework that includes the tools needed to create a robust web service client, including: Service descriptions for defining the inputs and outputs of an API, resource iterators for traversing paginated resources, batching for sending a large number of requests as efficiently as possible.

<?php
require_once 'vendor/autoload.php';
use Guzzle\Http\Client;

// Create a client to work with the Twitter API
$client = new Client('https://api.twitter.com/{version}', array(
    'version' => '1.1'
));

// Sign all requests with the OauthPlugin
$client->addSubscriber(new Guzzle\Plugin\Oauth\OauthPlugin(array(
    'consumer_key'    => '***',
    'consumer_secret' => '***',
    'token'           => '***',
    'token_secret'    => '***'
)));

echo $client->get('statuses/user_timeline.json')->send()->getBody();
// >>> {"public_gists":6,"type":"User" ...

// Create a tweet using POST
$request = $client->post('statuses/update.json', null, array(
    'status' => 'Tweeted with Guzzle, http://guzzlephp.org'
));

// Send the request and parse the JSON response into an array
$data = $request->send()->json();
echo $data['text'];
// >>> Tweeted with Guzzle, http://t.co/kngJMfRk

Guzzle →

Simple REST API Explorer

Just pushed a new project to GitHub named Simple REST API Explorer, a simple way to showcasing and exploring all endpoints of your RESTful API.

The demo allows you to call some Twitter API endpoints a sample RESTful API I’ve quickly knocked up as the Twitter API is rather unstructured. Update the index.html file to reflect your own API endpoints. All the rest will go automagically.

Some notes that go with this first version:

  • Only tested with APIs returning JSON or JSONP.
  • Custom headers don’t work with JSONP. If you do need both JSONP and an API-Key: ask your API provider to enable CORS so you can switch to JSON.
  • Only GET supported (for now?) Already fixed 😉

Simple REST API Explorer Demo →
Simple REST API Explorer Source (GitHub) →