Open Stack

Jamie (and whom ever else wants to jump in),

It's been proposed to use json schema to describe the API calls rather
than code. The operations to perform and what they do would be
described rather than coded and then some code would use the schema to
know how to act.

Others are already doing this. For example, the AWS SDK for PHP. Take
their S3 structure as an example
https://github.com/aws/aws-sdk-php/blob/master/src/Aws/S3/Resources/s3-2006-03-01.php.
The ability to do this goes beyond this one example. It just appears
to be something similar to what we're considering.

Given this in the scope of PHP I've got a number of questions. Several
of these I've compiled while discussing this with others so they don't
represent my point of view. Rather, they are just a list of
outstanding questions. Since this is a different method for handling
the API calls from the other SDKs being built the concept should be
really vetted.

Here are the questions:

1. Why use json schema rather than other reuse methods? I've discussed
the use of json schemas with others and those working on the other
languages have not been interested in json schema at the moment. Why
do it differently given the context?

Note, it might be worth looking at the python SDK which is doing
things differently. If I understand it right they are moving aware
from using managers and resources all together.

2. How will debugging work in practice? For example, a call is made
from behind a proxy. The proxy alters the HTTP headers so the request
fails and an exception is thrown. The schema and endpoint are valid.
It's something in the middle that changed things. Walking through the
code goes through magic methods to handle the schema. How would
debugging that work to understand what's happening compared to what
was expected.

3. Where would the json schemas for services come from and who would
manage them?

4. What would the workflow look like for working with the schemas at
both execution time for everyday use and for testing?

5. How would logic happen? Sometimes a request to an API is more than
just a request and response. For example, calling to something in
object storage where the object does not exist. The transport layer
will throw an exception (this goes all the way down to Guzzle throwing
one) that needs to be caught and managed. How should cases with some
logic like this be handled and easy to understand?

Thanks for looking into this. The topic has really sparked my
interest. I for one am really curious about the practicalities of
using json schema and the developer experience around it.

- Matt Farina