PHPNews

Picking the right API Paradigm

A while back I wrote an article called Understanding RPC, REST and GraphQL which outlined the "what" in how these various approaches differ. This got a few people thinking I was saying REST was drastically superior in all ways, which is a common conclusion when folks hear me describe REST as a layer of abstractions …

Continue reading »

Written by Phil Sturgeon - - Aggregated on Monday May 21, 2018


API Evolution for REST/HTTP APIs

There are a lot of pros and cons to various approaches to API versioning, but that has been covered in depth before: API Versioning Has No "Right" Way . API evolution is making a comeback these days with GraphQL and gRPC advocates shouting about it. Whatever API paradigm or implementation you subscribe to, …

Continue reading »

Written by Phil Sturgeon - - Aggregated on Wednesday May 2, 2018


Solving OpenAPI and JSON Schema Divergence

My previous article explained the divergence between OpenAPI and JSON Schema (a.k.a the subset/superset/sideset problem), and promised solutions. One of those solutions is a tangible thing, which you can install right now! The other is now ready for tool vendors to start considering. To briefly recap: OpenAPI …

Continue reading »

Written by Phil Sturgeon - - Aggregated on Friday April 13, 2018


OpenAPI and JSON Schema Divergence: Part 1

This article is going to explain the divergence between OpenAPI and JSON Schema, which I've been calling the subset/superset/sideset problem. It'll finish up explaining how we're going to solve it, and ~I'll write part 2 when it is solved~ part two explains the solution . Whenever talking about API specification…

Continue reading »

Written by Phil Sturgeon - - Aggregated on Friday March 30, 2018


Still Going on REST is the new SOAP

One month after A Response to REST is the new SOAP and I'm still having a productive dialog with the author, helping him understand how REST works. I thought it might interest some of you too. Pakal de Bonchamp Thanks for the lengthy article - we unexpectedly agree on many things. I'll try to summarize my …

Continue reading »

Written by Phil Sturgeon - - Aggregated on Saturday January 20, 2018


A Response to REST is the new SOAP

Enough people have asked me about the article REST is the new SOAP that I felt it justifies a write up. Before I get started, I want to be clear that I hold no grudge against the author, and if any frustration leaks out in my writing I'd like to apologize in advance. The entire article is full of common …

Continue reading »

Written by Phil Sturgeon - - Aggregated on Monday December 18, 2017


One Month Since OpenAPI v3.0

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 …

Continue reading »

Written by Phil Sturgeon - - Aggregated on Saturday August 26, 2017


Chasing the Perfect API Specification Workflow

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 …

Continue reading »

Written by Phil Sturgeon - - Aggregated on Thursday July 20, 2017


Representing State in REST and GraphQL

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 …

Continue reading »

Written by Phil Sturgeon - - Aggregated on Monday June 19, 2017


You Might Not Need GraphQL

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 …

Continue reading »

Written by Phil Sturgeon - - Aggregated on Monday April 17, 2017


GraphQL vs REST: Caching

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 …

Continue reading »

Written by Phil Sturgeon - - Aggregated on Thursday January 26, 2017


GraphQL vs REST: Overview

A few months back I wrote a comparison between RPC and REST for Smashing Magazine, and now I want to talk about the differences between REST and GraphQL: the new kid on the block. GraphQL is incorrectly considered by some to be a "replacement" to REST . GraphQL is a newer concept, being released by Facebook …

Continue reading »

Written by Phil Sturgeon - - Aggregated on Tuesday January 24, 2017


Building APIs with Rails: Documentation Testing

Now that we've started building a very basic API, we should make sure that the documentation continues to keep up to date with our progress. Even better, we can use our documentation as a basic contract test, to make sure we aren't lying about what our API offers. I've written tutorials in the past about how Dredd …

Continue reading »

Written by Phil Sturgeon - - Aggregated on Wednesday December 21, 2016


Building APIs with Rails: Documentation Testing

Now that we've started building a very basic API, we should make sure that the documentation is kept up to date with our progress. Even better, we can use our documentation as a basic contract test, to make sure we aren't lying about what our API offers. I've written tutorials in the past about how Dredd works , …

Continue reading »

Written by Phil Sturgeon - - Aggregated on Wednesday December 21, 2016


Mocking APIs with API Blueprint

The second video in a pile of LiveCoding.tv videos shows how to use your API Blueprint documentation to mock APIs, and a few different ways of serving those mocks up to people. Using a mock server, you can basically see how an API would work, without actually building anything. This is really helpful as early on …

Continue reading »

Written by Phil Sturgeon - - Aggregated on Friday December 2, 2016