Phil Sturgeon philsturgeon

Taken verbatim from https://www.congress.gov/bill/114th-congress/house-bill/2029/text

   TITLE &lt;&lt;NOTE: Visa Waiver Program Improvement and Terrorist Travel 
  Prevention Act of 2015.&gt;&gt;  II--TERRORIST TRAVEL PREVENTION AND VISA 
WAIVER PROGRAM REFORM
SEC. 201. &lt;&lt;NOTE: 8 USC 1101 note.&gt;&gt; SHORT TITLE.

    This title may be cited as the ``Visa Waiver Program Improvement and 
Terrorist Travel Prevention Act of 2015''.

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

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.

As a refinement to his previously published book, the author of "Building APIs You Won't Hate" found that API books and training tends to introduce documentation, testing and caching as an after-thought, as if these are not important. However, some new experiences have shown that API development works best when these items are thought out first, as well as including a strong pragmatic approach to ensure the API solves real problems without getting stuck on the theory of how to "properly" create it.

Other pragmatic talking points include: Why and how documentation first can stop your team(s) from getting violent, when is REST not what you want, why is hypermedia sometimes a distraction, convenient ways to avoid versions in your API or at least postpone it, and comprehensive but simple endpoint integration testing beyond trivial examples.

FORMAT: 1A
# My API

## GET /places

+ Response 200 (text/plain)

Moved to

	<?php

	class Example
	{
	public $number;
	public $text;

	public function __construct(int $number, string $text)
	{
	$this->number = $number;

	# Somewhere, maybe in ApplicationController
	def whitelist_relationships(params)
	whitelist = %w(driver seats driver.avatar)
	params[:include].split(/,/) & whitelist if params[:include].present?
	end

	# Then when rendering the resource
	render json: Array(@resources), root: :trips, include: whitelist_relationships(params)

	$ irb
	irb(main):001:0> "text" * 4
	=> "texttexttexttext"

	$ php -a
	Interactive shell

	php > var_dump("text" * 4);
	int(0)