Skip to content

Instantly share code, notes, and snippets.

Not Riding Bikes

Phil Sturgeon philsturgeon

Not Riding Bikes
Block or report user

Report or block philsturgeon

Hide content and notifications from this user.

Learn more about blocking users

Contact Support about this user’s behavior.

Learn more about reporting abuse

Report abuse
View GitHub Profile
philsturgeon / cloudSettings
Last active Nov 19, 2019
Visual Studio Code Settings Sync Gist
View cloudSettings
philsturgeon /
Last active Feb 23, 2019
OpenAPI specifications style guide / file format

API Specs & Docs

Style Guide

A lot of this information has been used to create linting rules for [Speccy], so just run the linter with --rules=strict for advice. It will be updated over time, as new rules are created.

File Structure

OpenAPI supports JSON Pointer via $ref keys, even when you’re writing in YAML. has a great guide for $ref and JSON Pointer.

philsturgeon / Gemfile
Created Dec 14, 2017
Faraday Adapters Benchmark
View Gemfile
source ''
gem 'faraday'
gem 'net-http-persistent'
gem 'typhoeus'
gem 'patron'
gem 'httpclient'
gem 'net-http2'
philsturgeon /
Last active Dec 7, 2017
Postman disagrees with itself

Hey, I’m super lost.

Currently im trying to make API Flow work:

There is an output.json which is a test case, and accoring to Postmans JSON Schema it is invalid.

I'm fixing a few (headers cannot have a null value) but the auth section is triggering errors. It looks like this:

View gist:bfabe7461ec6faf9457b6a75f25c0d9c
class Api::V3::CompanyPresenter
attr_accessor :company, :includes
def initialize(company, includes: [])
@company = company
@includes = Array(includes)
def as_json
philsturgeon / gist:64f7b611a035084b39673853c7e43f0d
Last active Jun 8, 2017
Janky Quick Example of RPC API being cool
View gist:64f7b611a035084b39673853c7e43f0d

POST /check-v1


  "user_uuid" : "12345",
  "policy_action" : "do-a-thing"
View shitly formatted

Taken verbatim from

   TITLE <<NOTE: Visa Waiver Program Improvement and Terrorist Travel 
SEC. 201. <<NOTE: 8 USC 1101 note.>> SHORT TITLE.

    This title may be cited as the ``Visa Waiver Program Improvement and 
Terrorist Travel Prevention Act of 2015''.
philsturgeon /
Created Nov 2, 2016
Get those tests outta here!
bundle exec rspec | grep -ohi 'rspec \./[^\:]*' | sed -e 's/^rspec //' | while read f; do [[ -a "$f" ]] && git rm "$f"; done

Option 1

Modifying a global resource can feel a bit weird, but essentially as an authorized user, you are looking at your customized representation of the resource, and not just a direct 1:1 of whats in the database.

  • Like: PATCH /bars/123 with field liked: true
  • Unlike: PATCH /bars/123 with field liked: false

This can feel a bit weird if you consider it as corrupting the global value, but headers often change the response and that's probably fine. It can be weird to show different attributes depending on the user (I avoid this) but you can probably jam it in meta as the JSON-API allows this already? It's relevant data, just not necessairily part of the resource.

Option 2

philsturgeon /
Created Mar 31, 2016
What Rails Can Teach PHP About Building APIs

As somebody who's built APIs with PHP since 2009, and built APIs with Rails for the last two years, the contrast in some of the tooling available is mind-blowing. When it comes to factories for generating test data, spec-driven testing with tools like RSpec, mutation testing, simplistic state machines, serialization and deserialization in JSON-API, REPL debugging with breakpoints, file upload handlers, etc., Ruby (and Rails) very often has a strong lead in maturity of the tooling.

Objectively speaking, PHP either does not have some of these tools, or they're immature in comparison. This is by no means a fault of PHP as a language or a community. Ruby has had Gems for far longer than PHP has had Composer, and while PHP is starting to learn how to get this done in a post-framework-everything world, it has a way to go.

This talk looks at some of the cool stuff Ruby can do, and some of the lesser known tools that provide similar functionality in PHP.

You can’t perform that action at this time.