The SitePoint PHP blog has a new post today introducing RAML, a modeling language made specifically for use in APIs to define services available.

n a recent article I introduced Slate, a static site generator specifically designed for writing API documentation. This time around, I’m going to look at something which in many ways is even better. But first, if you’ll indulge me for just a moment, I’d like to begin by quoting myself from that article; "[an] API is only as good as its documentation." I think it’s worth repeating, since it’s all-too-frequently overlooked, and it’s one of the motivations for this short series of articles on some of the tools out there to help you write great documentation.

RAML (RESTful API Modeling Language) provides a structured, unambiguous format for describing a RESTful API. It allows you to describe your API; the endpoints, the HTTP methods to be used for each one, any parameters and their format, what you can expect by way of a response and more.

He starts off with a few things that RAML is particularly good at helping with, including being used to generate other documentation. He then moves into writing up some of the actual RAML documentation, noting that it's a derivative of YAML and is just made from text files. He walks through the creation of a sample RAML document including the overall summary information, describing resources, HTTP methods and response structure. He also includes examples of defining query parameters, request data and any security requirements you might have. Finally, he suggests the raml2html tool if you want to generate some HTML output of your configuration, making it easier for normal humans to read.

Arnold Daniels has posted some thoughts on a topics recently featured in a cover story by php|architect - EAV modeling.

I had seen this db structure in other project, but didn't know that it was called EAV. For those who don't read php|architect, EAV describes a method of saving a large set of attributes, only some of which apply to an individual entity. Normally you would create a table, with a row for each entity and save each attribute in a column. With EAV you save each attribute as a row.

He suggests two ways to do the modeling - the more "common" way and an alternative way that splits up the data types to make querying simpler (into scalars and arrays). A sample database structure and example query for it are included.

Matthew Turland has posted about a topic that was the subject of a recent cover story in php|architect magazine - EAV modeling.

The mental image that came to me when reading about this approach to data modeling was taking the traditional relational table and turning it on its head. [...] EAV actually has to circumvent, work around, or reimplement features that most mainstream database servers today provide "for free" to the traditional relational counterparts of EAV in order to get equal functionality.

He talks about features the structure has (including row-level referential integrity and schema metadata) and points out some of the other document-focused database systems like Lucene and CouchDB.

Check out the story in the June 2008 issue of php|architect for that cover story from Carl Welch.