The SitePoint PHP blog has a new tutorial posted today showing you how to test your API via RAML, using the structure it defines to verify the requests and responses made to the API. This is the second part of the series and you can find part one (the introduction to RAML) here.

In a recent article I looked at RESTful API Modeling Language (RAML). I provided an overview of what RAML is all about, how to write it and some of its uses. This time, I’m going to look at some of the ways in which you can use RAML for testing. We’ll start by using RAML to validate responses from an API. Then we’ll look at an approach you could take to mock an API server, using a RAML file to create mock HTTP responses.

He starts off by defining a basic RAML document that defines an "Albums" structure with endpoints for "account" and "albums" with various data beneath each one (and created an application that follows it). He then shows how to combine Guzzle, PHPUnit and a RAML parser to grab the API definition and set up a sample test. A simple example test is provided showing you how to check the validity of a response structure. Then he gets into mocking the API using the RAML structure using the FastRoute router. He creates a mock object and a "dispatch" method to handle the request routing based on the contents of the RAML document. He also includes a method to check the parameter values on a request, ensuring they're the correct types.

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.