Re: [openstack-dev] [openstack-sdk-php] discussion: json schema to define apis
Ken'ichi, thanks for the detail. I just added that summit session to my list to attend. I'm looking forward to it. On Thu, May 1, 2014 at 12:34 AM, Ken'ichi Ohmichi ken1ohmi...@gmail.comwrote: Hi, 2014-04-29 10:28 GMT+09:00 Matthew Farina m...@mattfarina.com: *3. Where would JSON schemas come from?* It depends on each OpenStack service. Glance and Marconi (soon) offer schemas directly through the API - so they are directly responsible for maintaining this - we'd just consume it. We could probably cache a local version to minimize requests. For services that do not offer schemas yet, we'd have to use local schema files. There's a project called Tempest which does integration tests for OpenStack clusters, and it uses schema files. So there might be a possibility of using their files in the future. If this is not possible, we'd write them ourselves. It took me 1-2 days to write the entire Nova API. Once a schema file has been fully tested and signed off as 100% operational, it can be frozen as a set version. Can we convert the schema files from Tempest into something we can use? just FYI Now Tempest contains schemas for Nova API only, and the schemas of request and response are stored into different directories. We can see request schema: https://github.com/openstack/tempest/tree/master/etc/schemas/compute response schema: https://github.com/openstack/tempest/tree/master/tempest/api_schema/compute In the future, the way to handle these schemas in Tempest is one of the topics in the next summit. http://junodesignsummit.sched.org/event/e3999a28ec02aa14b69ad67848be570a Nova also contains request schema under https://github.com/openstack/nova/tree/master/nova/api/openstack/compute/schemas/v3 These schemas are used only for Nova v3 API, there is nothing for v2 API(current) because v2 API does not use jsonschema. Thanks Ken'ichi Ohmichi ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [openstack-sdk-php] discussion: json schema to define apis
Hi, 2014-04-29 10:28 GMT+09:00 Matthew Farina m...@mattfarina.com: *3. Where would JSON schemas come from?* It depends on each OpenStack service. Glance and Marconi (soon) offer schemas directly through the API - so they are directly responsible for maintaining this - we'd just consume it. We could probably cache a local version to minimize requests. For services that do not offer schemas yet, we'd have to use local schema files. There's a project called Tempest which does integration tests for OpenStack clusters, and it uses schema files. So there might be a possibility of using their files in the future. If this is not possible, we'd write them ourselves. It took me 1-2 days to write the entire Nova API. Once a schema file has been fully tested and signed off as 100% operational, it can be frozen as a set version. Can we convert the schema files from Tempest into something we can use? just FYI Now Tempest contains schemas for Nova API only, and the schemas of request and response are stored into different directories. We can see request schema: https://github.com/openstack/tempest/tree/master/etc/schemas/compute response schema: https://github.com/openstack/tempest/tree/master/tempest/api_schema/compute In the future, the way to handle these schemas in Tempest is one of the topics in the next summit. http://junodesignsummit.sched.org/event/e3999a28ec02aa14b69ad67848be570a Nova also contains request schema under https://github.com/openstack/nova/tree/master/nova/api/openstack/compute/schemas/v3 These schemas are used only for Nova v3 API, there is nothing for v2 API(current) because v2 API does not use jsonschema. Thanks Ken'ichi Ohmichi ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [openstack-sdk-php] discussion: json schema to define apis
Thanks Matt for bringing up these questions - I think having this kind of discussion is essential for such a big idea. It also helps me clarify my own thinking towards this issue. Before I answer, I want to point out that I'm not staunchly for or against any particular idea. I do think that schemas offer a lot of advantages over writing user-land code, but I'm more than willing to abandon the proposal if we all determine there's a stronger and more compelling alternative. 1. Why use schemas instead of userland code? I've put my answer to this question here: https://wiki.openstack.org/wiki/OpenStack-SDK-PHP/JSON-schema 2. How will debugging work? I'll highlight two conceivable issues which might need debugging. The first issue is the API rejecting a request for whatever reason (i.e. a proxy modifying headers); the second issue is when a data structure returned from the API fails to validate against a particular schema file. Issue 1: Malformed requests There are two reasons why a request would fail: if an end-user stocks it with bad data, or if something in the middle deforms it. A very easy solution to the first problem is using schemas to perform basic parameter checking before a request is serialized. If we know, for example, that the API is expecting a particular value - or a particular header - the schema is in charge of making that happen. Performing basic validation catches most errors - and debugging is very easy due to the exception thrown. If you're ever in doubt, you just refer to the schema to see what was serialized into a request in the same way you do for a concrete class method. If something in the middle deforms the request, the API will naturally reject it. When it comes to debugging this issue, all you need to do is wrap your original code in a try/catch block and use Guzzle's BadResponseException to return the API's response. You can easily see the type of failure through the HTTP status code, and the exact reason why the request failed. So it doesn't matter where the failure happens - all that matters is that there's a way to catch and spit out the API's response and the originating request. Issue 2: Incorrect API data Say we've defined that a Server has two properties: a name (which is a string) and metadata (which is an object). If the API returns a name as an array, that obviously fails validation. When the schema code goes to validate the API data, it will raise validation error when it comes to validate that name property. How you consequently use this validation error them is completely up to you: you could output it to STDOUT, you could save it to a local log on the filesystem, you could buffer it temporarily in memory. Any API data that does not validate successfully against a schema should not be presented to the end-user. So if a created_date property is returned, that isn't defined in our schema, it should not be populated in the resulting model. The model returned to the end-user would be a simple object that implements \ArrayAccess, meaning that it can be accessed like a simple array. 3. Where would JSON schemas come from? It depends on each OpenStack service. Glance and Marconi (soon) offer schemas directly through the API - so they are directly responsible for maintaining this - we'd just consume it. We could probably cache a local version to minimize requests. For services that do not offer schemas yet, we'd have to use local schema files. There's a project called Tempest which does integration tests for OpenStack clusters, and it uses schema files. So there might be a possibility of using their files in the future. If this is not possible, we'd write them ourselves. It took me 1-2 days to write the entire Nova API. Once a schema file has been fully tested and signed off as 100% operational, it can be frozen as a set version. 4. What would the workflow look like? I don't really understand what you mean: can you elaborate? 5. How does schema files handle business logic? That's a really great question. I've written a brief write-up here: https://wiki.openstack.org/wiki/OpenStack-SDK-PHP/JSON-schema-business-logichttps://wiki.openstack.org/wiki/OpenStack-SDK-PHP/JSON-schema-business-logic#So_how_can_it_be_done_well.3F Jamie From: Matthew Farina m...@mattfarina.commailto:m...@mattfarina.com Date: Thursday, April 24, 2014 at 5:42 PM To: Jamie Hannaford jamie.hannaf...@rackspace.commailto:jamie.hannaf...@rackspace.com, OpenStack Development Mailing List (not for usage questions) openstack-dev@lists.openstack.orgmailto:openstack-dev@lists.openstack.org Cc: sam.c...@hp.commailto:sam.c...@hp.com sam.c...@hp.commailto:sam.c...@hp.com Subject: [openstack-sdk-php] discussion: json schema to define apis 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
Re: [openstack-dev] [openstack-sdk-php] discussion: json schema to define apis
While reading this it struck me that we should prioritize the experience of
end-user, that is application developers, over the experience of those
working on the SDK. I don't think we'd ever directly talked about this so I
wanted to take a moment and state it.
What I put in below isn't my full set of questions but I think it's enough
for now.
On Mon, Apr 28, 2014 at 11:34 AM, Jamie Hannaford
jamie.hannaf...@rackspace.com wrote:
Thanks Matt for bringing up these questions - I think having this kind
of discussion is essential for such a big idea. It also helps me clarify my
own thinking towards this issue.
Before I answer, I want to point out that I'm not staunchly for or
against any particular idea. I do think that schemas offer a lot of
advantages over writing user-land code, but I'm more than willing to
abandon the proposal if we all determine there's a stronger and more
compelling alternative.
*1. Why use schemas instead of userland code?*
I've put my answer to this question here:
https://wiki.openstack.org/wiki/OpenStack-SDK-PHP/JSON-schema
Can we look at this from the experience an end user would have? In the
Python SDK they are working on an ORM style system. It's sorta similar to
the system currently in the PHP SDK. For example you could do something
like this in Python,
o = Container.get_by_id('foo').get_object('bar/baz.awesome')
I would imagine something similar in PHP like,
$o = $objectStore-getContainer('foo')-getObject('bar/baz.awesome');
I don't think you can do this using the json schema code I've seen so far.
Can you touch on the experience for developers who are using the library?
For example, the coding style or ability to know what they have access to?
I was just thinking of how magic methods using a schema aren't going to
work for tools that do autocompletion.
I'm curious about blueprints for the schema support. Things on the mailing
list are great. I'm curious about plans and what's in the blueprints. Do
you have any info on that?
If the other SDKs aren't interested in using json schema, wouldn't that be
a lack of consistency?
*2. How will debugging work?*
I'll highlight two conceivable issues which might need debugging. The
first issue is the API rejecting a request for whatever reason (i.e. a
proxy modifying headers); the second issue is when a data structure
returned from the API fails to validate against a particular schema file.
*Issue 1: Malformed requests*
There are two reasons why a request would fail: if an end-user stocks it
with bad data, or if something in the middle deforms it. A very easy
solution to the first problem is using schemas to perform basic parameter
checking before a request is serialized. If we know, for example, that the
API is expecting a particular value - or a particular header - the schema
is in charge of making that happen. Performing basic validation catches
most errors - and debugging is very easy due to the exception thrown. If
you're ever in doubt, you just refer to the schema to see what was
serialized into a request in the same way you do for a concrete class
method.
If something in the middle deforms the request, the API will naturally
reject it. When it comes to debugging this issue, all you need to do is
wrap your original code in a try/catch block and use Guzzle's
BadResponseException to return the API's response. You can easily see
the type of failure through the HTTP status code, and the exact reason why
the request failed. So it doesn't matter where the failure happens - all
that matters is that there's a way to catch and spit out the API's response
and the originating request.
First, this assumes Guzzle. Since we aren't tightly coupled to Guzzle we
can't always assume that. But, for practical purposes we can assume it for
now.
I was curious how things would work in PHP, such as the stack trace. For
magic methods you'll have a call to the magic method and to __call() where
the logic actually sits. In a debugger you'll be able to step through this
just fine.
One thing that may be more difficult is that knowing how the json schema
system works to debug and understand what's going on. How the schemas work
and how something gets translated into a method. Walking through a few
methods that are extended would be less logic to understand in the process.
I'm curious how the debugging experience would be for an end user who
doesn't know the json schema system but is using the library. Out of
curiosity I might try to find some time to sit down with some PHP
developers and see how they handle the debugging experience.
*Issue 2: Incorrect API data *
Say we've defined that a Server has two properties: a name (which is a
string) and metadata (which is an object). If the API returns a name as an
array, that obviously fails validation. When the schema code goes to
validate the API data, it will raise validation error when it comes to
validate that name property. How you
Re: [openstack-dev] [openstack-sdk-php] discussion: json schema to define apis
Jamie, thanks for going into so much detail.
On Mon, Apr 28, 2014 at 9:28 PM, Matthew Farina m...@mattfarina.com wrote:
While reading this it struck me that we should prioritize the experience
of end-user, that is application developers, over the experience of those
working on the SDK. I don't think we'd ever directly talked about this so I
wanted to take a moment and state it.
What I put in below isn't my full set of questions but I think it's enough
for now.
On Mon, Apr 28, 2014 at 11:34 AM, Jamie Hannaford
jamie.hannaf...@rackspace.com wrote:
Thanks Matt for bringing up these questions - I think having this kind
of discussion is essential for such a big idea. It also helps me clarify my
own thinking towards this issue.
Before I answer, I want to point out that I'm not staunchly for or
against any particular idea. I do think that schemas offer a lot of
advantages over writing user-land code, but I'm more than willing to
abandon the proposal if we all determine there's a stronger and more
compelling alternative.
*1. Why use schemas instead of userland code?*
I've put my answer to this question here:
https://wiki.openstack.org/wiki/OpenStack-SDK-PHP/JSON-schema
Can we look at this from the experience an end user would have? In the
Python SDK they are working on an ORM style system. It's sorta similar to
the system currently in the PHP SDK. For example you could do something
like this in Python,
o = Container.get_by_id('foo').get_object('bar/baz.awesome')
I would imagine something similar in PHP like,
$o = $objectStore-getContainer('foo')-getObject('bar/baz.awesome');
I don't think you can do this using the json schema code I've seen so far.
Can you touch on the experience for developers who are using the library?
For example, the coding style or ability to know what they have access to?
I was just thinking of how magic methods using a schema aren't going to
work for tools that do autocompletion.
I'm curious about blueprints for the schema support. Things on the mailing
list are great. I'm curious about plans and what's in the blueprints. Do
you have any info on that?
If the other SDKs aren't interested in using json schema, wouldn't that be
a lack of consistency?
*2. How will debugging work?*
I'll highlight two conceivable issues which might need debugging. The
first issue is the API rejecting a request for whatever reason (i.e. a
proxy modifying headers); the second issue is when a data structure
returned from the API fails to validate against a particular schema file.
*Issue 1: Malformed requests*
There are two reasons why a request would fail: if an end-user stocks it
with bad data, or if something in the middle deforms it. A very easy
solution to the first problem is using schemas to perform basic parameter
checking before a request is serialized. If we know, for example, that the
API is expecting a particular value - or a particular header - the schema
is in charge of making that happen. Performing basic validation catches
most errors - and debugging is very easy due to the exception thrown. If
you're ever in doubt, you just refer to the schema to see what was
serialized into a request in the same way you do for a concrete class
method.
If something in the middle deforms the request, the API will naturally
reject it. When it comes to debugging this issue, all you need to do is
wrap your original code in a try/catch block and use Guzzle's
BadResponseException to return the API's response. You can easily see
the type of failure through the HTTP status code, and the exact reason why
the request failed. So it doesn't matter where the failure happens - all
that matters is that there's a way to catch and spit out the API's response
and the originating request.
First, this assumes Guzzle. Since we aren't tightly coupled to Guzzle we
can't always assume that. But, for practical purposes we can assume it for
now.
I was curious how things would work in PHP, such as the stack trace. For
magic methods you'll have a call to the magic method and to __call() where
the logic actually sits. In a debugger you'll be able to step through this
just fine.
One thing that may be more difficult is that knowing how the json schema
system works to debug and understand what's going on. How the schemas work
and how something gets translated into a method. Walking through a few
methods that are extended would be less logic to understand in the process.
I'm curious how the debugging experience would be for an end user who
doesn't know the json schema system but is using the library. Out of
curiosity I might try to find some time to sit down with some PHP
developers and see how they handle the debugging experience.
*Issue 2: Incorrect API data *
Say we've defined that a Server has two properties: a name (which is a
string) and metadata (which is an object). If the API returns a name as an
array, that
Re: [openstack-dev] [openstack-sdk-php] discussion: json schema to define apis
Yes, thanks Jamie for the very thorough write ups and Matt for the thoughtful
comments.
My comments are inline below. A point of clarification: I’m using “SDK authors”
to mean all of us who are building the SDK and I’m using “SDK consumers” to
mean the end-user developers who will be using the SDK.
Thanks,
Shaunak
On Apr 28, 2014, at 6:29 PM, Matthew Farina m...@mattfarina.com wrote:
Jamie, thanks for going into so much detail.
On Mon, Apr 28, 2014 at 9:28 PM, Matthew Farina m...@mattfarina.com wrote:
While reading this it struck me that we should prioritize the experience of
end-user, that is application developers, over the experience of those
working on the SDK. I don't think we'd ever directly talked about this so I
wanted to take a moment and state it.
What I put in below isn't my full set of questions but I think it's enough
for now.
On Mon, Apr 28, 2014 at 11:34 AM, Jamie Hannaford
jamie.hannaf...@rackspace.com wrote:
Thanks Matt for bringing up these questions - I think having this kind of
discussion is essential for such a big idea. It also helps me clarify my own
thinking towards this issue.
Before I answer, I want to point out that I'm not staunchly for or against
any particular idea. I do think that schemas offer a lot of advantages over
writing user-land code, but I'm more than willing to abandon the proposal if
we all determine there's a stronger and more compelling alternative.
1. Why use schemas instead of userland code?
I've put my answer to this question here:
https://wiki.openstack.org/wiki/OpenStack-SDK-PHP/JSON-schema
Can we look at this from the experience an end user would have? In the
Python SDK they are working on an ORM style system. It's sorta similar to
the system currently in the PHP SDK. For example you could do something like
this in Python,
o = Container.get_by_id('foo').get_object('bar/baz.awesome')
I would imagine something similar in PHP like,
$o = $objectStore-getContainer('foo')-getObject('bar/baz.awesome');
I don't think you can do this using the json schema code I've seen so far.
Can you touch on the experience for developers who are using the library?
For example, the coding style or ability to know what they have access to? I
was just thinking of how magic methods using a schema aren't going to work
for tools that do autocompletion.
Good point about the discoverability aspect. SDK consumers would need to refer
to schemas during development and IDEs might not be able to grok these like
they would a PHP API.
That said, the benefits mentioned on the wiki page still stand. Is there a way
for SDK authors to get the benefits of using schemas while giving SDK consumers
the benefits of an easily- and automatically-discoverable PHP API?
I'm curious about blueprints for the schema support. Things on the mailing
list are great. I'm curious about plans and what's in the blueprints. Do you
have any info on that?
If the other SDKs aren't interested in using json schema, wouldn't that be a
lack of consistency?
This concerns me less. Consistency is useful if there’s a significant overlap
amongst the consumers of different SDKs or, secondarily, amongst the authors of
the different SDKs. I’m not sure there are such significant overlaps.
2. How will debugging work?
I'll highlight two conceivable issues which might need debugging. The first
issue is the API rejecting a request for whatever reason (i.e. a proxy
modifying headers); the second issue is when a data structure returned from
the API fails to validate against a particular schema file.
Issue 1: Malformed requests
There are two reasons why a request would fail: if an end-user stocks it with
bad data, or if something in the middle deforms it. A very easy solution to
the first problem is using schemas to perform basic parameter checking before
a request is serialized. If we know, for example, that the API is expecting a
particular value - or a particular header - the schema is in charge of making
that happen. Performing basic validation catches most errors - and debugging
is very easy due to the exception thrown. If you're ever in doubt, you just
refer to the schema to see what was serialized into a request in the same way
you do for a concrete class method.
If I understand this right, the same code path would be used to perform basic
parameter checking regardless of the upstream service. The specific validation
rules for each upstream service would be represented in the schema. Given this
setup, when an exception is thrown, it would be awesome if we could point the
SDK consumer to the line/section of the schema where the violated validation
rule was defined. This way the exception is actionable for the SDK consumer.
If something in the middle deforms the request, the API will naturally reject
it. When it comes to debugging this issue, all you need to do is wrap your
