PHPNews

One Month Since OpenAPI v3.0

Written by Phil Sturgeon - Published on Phil Sturgeon's blog
Aggregated on Saturday August 26, 2017 - Permalink

Last month today OpenAPI v3.0 was released , and not only is there a lot of cool stuff , but it unblocks some akward situations with vendor prefixes and other lacking features. I was hoping the tooling would be hot on its tails. Progress is being made in all of the repositories I've got my eyes on, but sadly v3.0 support is not there yet. Marketing Even though the whole OpenAPI community …

Continue reading »


A Happy Compromise Between Customization and Cacheability

Written by Phil Sturgeon - Published on Phil Sturgeon's blog
Aggregated on Sunday August 13, 2017 - Permalink

With endpoint-based APIs (REST, RESTish, SOAP, RPC, AJAX-ish junk, etc.) you get to choose if you want increased likelihood of network cache hits, or the ability to slim down the response. The two goals are mutually exclusive. Slimming responses can be achieved with concepts like sparse fieldsets (tl:dr; send ?fields=foo,bar to just get foo and bar). This is common and popular for two …

Continue reading »


Chasing the Perfect API Specification Workflow

Written by Phil Sturgeon - Published on Phil Sturgeon's blog
Aggregated on Thursday July 20, 2017 - Permalink

Documentation is a nice thing to have, but it is often treated as optional or superfluous, especially in teams where the clients and servers are managed by the same people. Here the code is considered the contract, so why define it again in documentation? Certainly, with all the tooling around, API documentation seems like "another thing to do". You already have to define all the fields/types/…

Continue reading »


Representing State in REST and GraphQL

Written by Phil Sturgeon - Published on Phil Sturgeon's blog
Aggregated on Monday June 19, 2017 - Permalink

Representing state is a complex thing. At my last two jobs, it's been very common for APIs to be treated like "databases over HTTP". The fields are sent up and down from the server to multiple mobile/web apps, and there's not too much else going on. Over time, we noticed this specific problem happening over and over again: When you ask the clients to infer state from the fields alone, they …

Continue reading »


You Might Not Need GraphQL

Written by Phil Sturgeon - Published on Phil Sturgeon's blog
Aggregated on Monday April 17, 2017 - Permalink

After writing about how GraphQL and REST differ in various regards, and taking a closer look at caching in particular , I wanted to write about how you can get some of the benefits of GraphQL into an existing endpoint-based API. It's finally live, and over on the Runscope blog . Normally I'd post this sort of thing on here, but I've got a smashed racing bike to pay for , Runscope are …

Continue reading »


GraphQL vs REST: Caching

Written by Phil Sturgeon - Published on Phil Sturgeon's blog
Aggregated on Thursday January 26, 2017 - Permalink

Recently I wrote GraphQL vs REST: Overview , giving a hype-free outline of the differences between REST and GraphQL . One section that would not have fit into that already lengthy article was caching, so I thought I'd fire that out next. Comparing how caching is used for the two approaches is tricky, because despite common opinion, REST has nothing to do with HTTP. REST is usually …

Continue reading »