philsturgeon

bundle exec rspec | grep -ohi 'rspec \./[^\:]*' | sed -e 's/^rspec //' | while read f; do [[ -a "$f" ]] && git rm "$f"; done

philsturgeon

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

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.

philsturgeon

<?php

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

philsturgeon

# 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)

philsturgeon

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

$ php -a
Interactive shell

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

philsturgeon

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.

philsturgeon

FORMAT: 1A
# My API

## GET /places

+ Response 200 (text/plain)

philsturgeon

Moved to

philsturgeon

<?php

$foo = "global";

include "namespaced.php";

echo $foo; // Outputs: "something"