Create an API method

shatsar edited this page Nov 17, 2011 · 1 revision
Clone this wiki locally

It's time to create an API method for the component. The Mashape PHP Library is made of two files and a folder:

  • An api.php file, that will contain the method's implementation.
  • An api.xml file, an XML configuration file that contains the component's API configuration (which API methods to expose, how to serialize data, custom routes, etc).
  • A mashape folder, that contains the library itself.

The api.php and api.xml contain a simple hello world component, this means that they aren't strictly part of the Mashape PHP Library (that is located in the mashape folder).

API Methods

The component is implemented in the api.php file, inside the ComponentAPI class where all the API methods will be declared. An API method is a public function with an arbitrary number of parameters (optional parameters are allowed), that can return an object or not. Not all the functions declared in the ComponentAPI class will become API methods, but just those described in the XML configuration file. The objects returned by an API method are automatically serialized by the library according to the XML configuration. Basically there are two macrocategories of return objects:

  • Simple objects, that are plain text, numeric or boolean values.
  • Complex objects, that are custom declared objects like an User or a Comment object.

DRY: The API methods may require functions or objects defined outside the api.php file (like an existing Model). Just include in the api.php file all the dependencies you need.

Hello World

The Mashape PHP Library comes with an hello world example. The api.php file declares a sayHello function that returns a simple string object: The SERVER_KEY constant should be set with the server key code that will be given in the wizard. It's not required to be set properly until you decide to publish the component into the marketplace. The implementation itself is useless without the XML configuration file (api.xml) that describes which functions should become API methods, and also describes how to serialize the returned objects. The api.xml file for the Hello World component is the following: We've just described that the sayHello function is an API method callable with a GET request. It's also described that it returns a simple object whose value will be associated with an "helloWorldMessage" key. When an API method hasn't a custom route, you can call it locally without authenticating by making an HTTP request appending the _method parameter followed by all the parameters required for its execution, for example:


Boolean parameters When an HTTP request is made to an API method, all the parameters are by default string values. If a method requires a boolean parameter, it will be populated with a string value like "true" or "false". Note: PHP doesn't evaluate the "true" and "false" strings into a boolean value (it just work well with "1" and "0" strings). Before evaluating the parameter, parse it with the parent::parseBoolean($value) function (declared in the base MashapeRESTApi abstract class). For example: Optional parameters An API method may have optional parameters, that it's not required to set in the HTTP request: You can call the sayHello API method setting a value for the nick parameter

GET Or without setting it, in this case the default value will be taken:

GET Set a custom HTTP Status Code You can set a custom HTTP status code using the parent method parent::setHTTPStatusCode($HTTPStatusCode) HTTPStatusCode - The HTTP status code and its description, for example "201 Created" If more than one HTTP status code is set, the last one will be used.