<HTML>
<HEAD><!-- Template generated by Exclaimer Mail Disclaimers on 04:34:48 Monday, 28 April 2014 -->
<STYLE type=text/css>P.ae431132-9d17-4a38-b6b5-634369783623 {
MARGIN: 0cm 0cm 0pt
}
LI.ae431132-9d17-4a38-b6b5-634369783623 {
MARGIN: 0cm 0cm 0pt
}
DIV.ae431132-9d17-4a38-b6b5-634369783623 {
MARGIN: 0cm 0cm 0pt
}
TABLE.ae431132-9d17-4a38-b6b5-634369783623Table {
MARGIN: 0cm 0cm 0pt
}
DIV.Section1 {
page: Section1
}
</STYLE>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
</HEAD>
<BODY style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; color: rgb(0, 0, 0); font-size: 14px; font-family: Calibri, sans-serif;">
<P class=ae431132-9d17-4a38-b6b5-634369783623>
<div>
<div>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. </div>
<div><br />
</div>
<div>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.</div>
<div><br />
</div>
<div><b>1. Why use schemas instead of userland code?</b></div>
<div><br />
</div>
<div>I've put my answer to this question here: <a href="https://wiki.openstack.org/wiki/OpenStack-SDK-PHP/JSON-schema">https://wiki.openstack.org/wiki/OpenStack-SDK-PHP/JSON-schema</a></div>
<div><br />
</div>
<div><b>2. How will debugging work?</b></div>
<div><br />
</div>
<div>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.</div>
<div><br />
</div>
<div><i>Issue 1: Malformed requests</i></div>
<div>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<i> </i>what was serialized into a request in the same way you do for a concrete class method. </div>
<div><br />
</div>
<div>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. </div>
<div><br />
</div>
<div><i>Issue 2: Incorrect API data </i></div>
<div>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.</div>
<div><br />
</div>
<div>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.</div>
<div><br />
</div>
<div><b>3. Where would JSON schemas come from?</b></div>
<div><b><br />
</b></div>
<div>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.</div>
<div><br />
</div>
<div>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.</div>
<div><br />
</div>
<div><b>4. What would the workflow look like?</b></div>
<div><b><br />
</b></div>
<div>I don't really understand what you mean: can you elaborate?</div>
<div><br />
</div>
<div><b>5. How does schema files handle business logic?</b></div>
<div><br />
</div>
<div>That's a really great question. I've written a brief write-up here: <a href="https://wiki.openstack.org/wiki/OpenStack-SDK-PHP/JSON-schema-business-logic#So_how_can_it_be_done_well.3F">https://wiki.openstack.org/wiki/OpenStack-SDK-PHP/JSON-schema-business-logic</a></div>
<div><br />
</div>
<div><br />
</div>
<div>Jamie</div>
</div>
<div><br />
</div>
<span id="OLK_SRC_BODY_SECTION">
<div style="font-family:Calibri; font-size:11pt; text-align:left; color:black; BORDER-BOTTOM: medium none; BORDER-LEFT: medium none; PADDING-BOTTOM: 0in; PADDING-LEFT: 0in; PADDING-RIGHT: 0in; BORDER-TOP: #b5c4df 1pt solid; BORDER-RIGHT: medium none; PADDING-TOP: 3pt">
<span style=font-weight:bold>From: </span>Matthew Farina <<a href="mailto:matt@mattfarina.com">matt@mattfarina.com</a>><br />
<span style=font-weight:bold>Date: </span>Thursday, April 24, 2014 at 5:42 PM<br />
<span style=font-weight:bold>To: </span>Jamie Hannaford <<a href="mailto:jamie.hannaford@rackspace.com">jamie.hannaford@rackspace.com</a>>, "OpenStack Development Mailing List (not for usage questions)" <<a href="mailto:openstack-dev@lists.openstack.org">openstack-dev@lists.openstack.org</a>><br />
<span style=font-weight:bold>Cc: </span>"<a href="mailto:sam.choi@hp.com">sam.choi@hp.com</a>" <<a href="mailto:sam.choi@hp.com">sam.choi@hp.com</a>><br />
<span style=font-weight:bold>Subject: </span>[openstack-sdk-php] discussion: json schema to define apis<br />
</div>
<div><br />
</div>
<div>
<div>
<div>Jamie (and whom ever else wants to jump in),</div>
<div><br />
</div>
<div>It's been proposed to use json schema to describe the API calls rather</div>
<div>than code. The operations to perform and what they do would be</div>
<div>described rather than coded and then some code would use the schema to</div>
<div>know how to act.</div>
<div><br />
</div>
<div>Others are already doing this. For example, the AWS SDK for PHP. Take</div>
<div>their S3 structure as an example</div>
<div><a href="https://github.com/aws/aws-sdk-php/blob/master/src/Aws/S3/Resources/s3-2006-03-01.php">https://github.com/aws/aws-sdk-php/blob/master/src/Aws/S3/Resources/s3-2006-03-01.php</a>.</div>
<div>The ability to do this goes beyond this one example. It just appears</div>
<div>to be something similar to what we're considering.</div>
<div><br />
</div>
<div>Given this in the scope of PHP I've got a number of questions. Several</div>
<div>of these I've compiled while discussing this with others so they don't</div>
<div>represent my point of view. Rather, they are just a list of</div>
<div>outstanding questions. Since this is a different method for handling</div>
<div>the API calls from the other SDKs being built the concept should be</div>
<div>really vetted.</div>
<div><br />
</div>
<div>Here are the questions:</div>
<div><br />
</div>
<div>1. Why use json schema rather than other reuse methods? I've discussed</div>
<div>the use of json schemas with others and those working on the other</div>
<div>languages have not been interested in json schema at the moment. Why</div>
<div>do it differently given the context?</div>
<div><br />
</div>
<div>Note, it might be worth looking at the python SDK which is doing</div>
<div>things differently. If I understand it right they are moving aware</div>
<div>from using managers and resources all together.</div>
<div><br />
</div>
<div>2. How will debugging work in practice? For example, a call is made</div>
<div>from behind a proxy. The proxy alters the HTTP headers so the request</div>
<div>fails and an exception is thrown. The schema and endpoint are valid.</div>
<div>It's something in the middle that changed things. Walking through the</div>
<div>code goes through magic methods to handle the schema. How would</div>
<div>debugging that work to understand what's happening compared to what</div>
<div>was expected.</div>
<div><br />
</div>
<div>3. Where would the json schemas for services come from and who would</div>
<div>manage them?</div>
<div><br />
</div>
<div>4. What would the workflow look like for working with the schemas at</div>
<div>both execution time for everyday use and for testing?</div>
<div><br />
</div>
<div>5. How would logic happen? Sometimes a request to an API is more than</div>
<div>just a request and response. For example, calling to something in</div>
<div>object storage where the object does not exist. The transport layer</div>
<div>will throw an exception (this goes all the way down to Guzzle throwing</div>
<div>one) that needs to be caught and managed. How should cases with some</div>
<div>logic like this be handled and easy to understand?</div>
<div><br />
</div>
<div>Thanks for looking into this. The topic has really sparked my</div>
<div>interest. I for one am really curious about the practicalities of</div>
<div>using json schema and the developer experience around it.</div>
<div><br />
</div>
<div>- Matt Farina</div>
<div><br />
</div>
</div>
</div>
</span>
</P>
<P class=ae431132-9d17-4a38-b6b5-634369783623> </P>
<P class=ae431132-9d17-4a38-b6b5-634369783623>
<TABLE border=0 cellPadding=0 width=504>
<TBODY>
<TR>
<TD style="WIDTH: 270px" class=LEFT_ALIGNED><span style='font-family:Verdana; font-size:small; '>Jamie Hannaford</span><BR /><span style='font-family:Verdana; font-size:x-small; '>Software Developer III - CH</span></TD>
<TD style="WIDTH: 281px"><IMG alt="experience Fanatical Support" align=right src="cid:image1c586e.JPG@a2152bb4.4e8f8a7f" width=159 height=17 /></TD></TR>
<TR class=LEFT_ALIGNED>
<TD colSpan=2><IMG alt=LINE src="cid:image17b982.JPG@4e56aa20.418b85ec" width=504 height=4 /></TD></TR>
<TR>
<TD class=CONTACTINFO><span style='font-family:Calibri; '><table class=ae431132-9d17-4a38-b6b5-634369783623Table><tr><td><span style='font-family:Verdana; font-size:x-small; '>Tel: </span></td><td><span style='font-family:Verdana; font-size:x-small; '>+41434303908</span></td></tr><tr><td><span style='font-family:Verdana; font-size:x-small; '>Mob: </span></td><td><span style='font-family:Verdana; font-size:x-small; '>+41791009767</span></td></tr></table></span></TD>
<TD class=RIGHT_ALIGNED><IMG alt=Rackspace src="cid:imagec7f21a.JPG@d9afb951.44a79336" width=280 height=60 /></TD></TR>
<TR class=LEFT_ALIGNED>
<TD class=CONTACTINFO colSpan=2><IMG src="cid:image9a4264.JPG@60536089.42ac77e9" width=504 height=3 /></TD></TR></TBODY></TABLE></P>
<P class=ae431132-9d17-4a38-b6b5-634369783623> </P>
<P class=ae431132-9d17-4a38-b6b5-634369783623></P><span style="font-size: 11px;">Rackspace International GmbH a company registered in the Canton of Zurich, Switzerland (company identification number CH-020.4.047.077-1) whose registered office is at Pfingstweidstrasse 60, 8005 Zurich, Switzerland. Rackspace International GmbH privacy policy can be viewed at www.rackspace.co.uk/legal/swiss-privacy-policy<br>-<br>Rackspace Hosting Australia PTY LTD a company registered in the state of Victoria, Australia (company registered number ACN 153 275 524) whose registered office is at Suite 3, Level 7, 210 George Street, Sydney, NSW 2000, Australia. Rackspace Hosting Australia PTY LTD privacy policy can be viewed at www.rackspace.com.au/company/legal-privacy-statement.php<br>-<span style="font-size: 11px;"></span><br>Rackspace US, Inc, 5000 Walzem Road, San Antonio, Texas 78218, United States of America</span><br><span style="font-size: 11px;">Rackspace US, Inc privacy policy can be viewed at www.rackspace.com/information/legal/privacystatement</span><br><span style="font-size: 11px;">-</span><br><span style="font-size: 11px;">Rackspace Limited is a company registered in England & Wales (company registered number 03897010) whose registered office is at 5 Millington Road, Hyde Park Hayes, Middlesex UB3 4AZ.</span><br><span style="font-size: 11px;">Rackspace Limited privacy policy can be viewed at www.rackspace.co.uk/legal/privacy-policy</span><br><span style="font-size: 11px;">-</span><br><span style="font-size: 11px;">Rackspace Benelux B.V. is a company registered in the Netherlands (company KvK nummer 34276327) whose registered office is at Teleportboulevard 110, 1043 EJ Amsterdam.</span><br><span style="font-size: 11px;">Rackspace Benelux B.V privacy policy can be viewed at www.rackspace.nl/juridisch/privacy-policy</span><br><span style="font-size: 11px;">-</span><br><span style="font-size: 11px;">Rackspace Asia Limited is a company registered in Hong Kong (Company no: 1211294) whose registered office is at 9/F, Cambridge House, Taikoo Place, 979 King's Road, Quarry Bay, Hong Kong.</span><br><span style="font-size: 11px;">Rackspace Asia Limited privacy policy can be viewed at www.rackspace.com.hk/company/legal-privacy-statement.php</span><br><span style="font-size: 11px;">-</span><br><span style="font-size: 11px;">This e-mail message (including any attachments or embedded documents) is intended for the exclusive and confidential use of the individual or entity to which this message is addressed, and unless otherwise expressly indicated, is confidential and privileged information of Rackspace. Any dissemination, distribution or copying of the enclosed material is prohibited. If you receive this transmission in error, please notify us immediately by e-mail at abuse@rackspace.com and delete the original message. Your cooperation is appreciated.</span></BODY>
</HTML>