API Input and Output

Introduction

This document gives an overview of all of the settings and configuration that can be sent to Wave Framework API and how each of those settings affects the way the API works. It will also cover all of the possible variables that Wave Framework API may return as a response. This document here is a reference guide to Wave Framework API communication.

This document covers all of the input and output variables of core Wave Framework API. There are additional variables that are API Wrapper specific, which you can read more about in PHP API Wrapper and JavaScript API Wrapper documentation.

API Input - Flags and Configuration

Wave Framework expects API-specific configuration settings in a simple format. Every configuration flag or setting is prefixed with 'www-', which is called the Wave prefix since it resembles waves. When sending input data to Wave Framework API, then all of the data is sent as one input array. When HTTP request is made, then all of the POST and GET and other variables are merged into one input array the same way.

These are all the input flags and settings that can be sent to API as well as what each of these input flags does:

www-command

This is a required setting for most API call made. This variable defines what Controller and what method is called by the API. Usually the value consists of two keywords, separated by '-' character. For example, if 'www-command' is set to 'example-get', then 'example' controller is called with method 'get'. This controller would be loaded from /controllers/controller.example.php, for example.

If this value is set to 'www-create-session' then this calls a special functionality of API that creates a new session token for an API profile. This is covered more in detail in API Security documentation.

If this value is set to 'www-destroy-session' then this will delete the existing session token.

If this value is set to 'www-validate-session' then this will check if the session token is still valid.

www-controller

It is also possible to define this value instead of 'www-command'. This value only requires the name of the controller that API will call. For example, if this is set to 'example', then /controllers/controller.example.php is called.

To find what method the controller will return, API will look at the HTTP request method. So if GET request is made, then it attempts to call a method get() with the input data.

This allows to build controllers that conform to RESTful API approach where the HTTP request method defines what type of action is performed.

www-return-type

This tells API what type of data you expect the API to return. Wave Framework API deals internally with arrays, so data is submitted as an array and is returned as an array from controllers. But the API can also convert that array into multiple data formats that can be used by other systems.

These are the formats supported as the content type:

www-minify

If this is set to 1, then this tells API to attempt to minify the result using Minifier. This type of minifying only works if 'www-return-type' is set to 'xml', 'html', 'js', 'css' or 'rss'. Otherwise the result is kept without minification.

www-output

If set to 1, then this tells API to return the result by pushing the contents to the output buffer. This means that the result will also be returned together with appropriate headers, based on 'www-return-type' or 'www-content-type' (if set). This is, for example, how View data is returned, as Views are all written and then pushed to output buffer.

www-return-hash

If this is set to 1, then it asks API to calculate a validation hash with API profile secret key or session token and return it as a 'www-hash' value to the requesting user agent. This validation hash can be used by the user agent to check whether the response data has been tampered with or not. You can read more about this in API Security documentation.

www-return-timestamp

If this is set to 1, then it tells the API to return 'www-timestamp' value that has the timestamp of when the response was generated. This can be checked by the user agent to validate when the response was made. If validation hash is used, then this value cannot be tampered with without the validation hash becoming incorrect.

www-content-type

This is an overwrite. If this is sent to API, then it tells API that no matter what the 'www-return-type' value, the value of 'www-content-type' will be submitted as the content type of the returned result.

This is required for certain custom-case uses. For example, browsers tend to pre-format data within browser windows when they are not in HTML format. But if you submit data to a hidden iFrame and expect to return JSON, then the content type has to be set to 'text/html' instead, in order to make sure the contents are not automatically converted by the browser.

www-crypt-output

This tells the API to encrypt the output from the API, if set to 1. This will entirely encrypt and serialize the whole output that is returned from API as a response. This uses Rijndael 256 bit encryption with either secret key or session token and the user agent that requests crypted output will have to decrypt the data prior to getting access to the variables within.

www-cache-tags

This is either a single string or a comma-separated string of tags that will be used, in case the response will also be cached by the API. These tags can be useful later on when a Controller needs to delete some cache from the system.

For example, if you generate product information page and allow it to be cached for a long time and send 'www-cache-tags' value as 'products', then you can delete all cache that has that tag from within Controllers whenever you know that your product data has been changed. This allows for very fine-tuned cache architecture.

www-language

Wave Framework comes with a translations layer that can be used even when a website is built upon Wave Framework. Sometimes you need to have your API return results in a specific language. If this value is sent to API, then API will use translations of that language when Controller and/or view generates a response to that API request. This language keyword has to be defined in configuration and it needs translations in /resources/[language].translations.ini file.

www-state

This variable has nothing to do with State Class of Wave Framework or the state object that API uses at the time of request. This is a security keyword, if this value is sent to API, then API also returns that same value in response. This can be used to validate if a response is for the same request that was made, or not. You can read more about this variable in API Security documentation.

www-data

This usually carries input stream data, if sent. This is used only when submitting contents in POST as input stream.

www-cache-timeout

This tells the API the amount of seconds that the user agent is accepting as the maximum age of cache. This means that if you send the value as 600 and API finds cache for that same API call with the same input within the last 600 seconds - or ten minutes - then it will return a result from cache instead of generating it again.

This allows for a lot of flexibility as it is an on-demand cache-control that can be used to speed up requests or the same Controller in some parts of the system based on their importance.

www-cache-load-timestamp

This tells the API to accept cache with different timestamp based age than the 'www-cache-timeout' value. This means that you can make a request that only allows 'www-cache-load-timestamp' aged cache, but writes a different cache age to headers and for other methods.

www-profile

This is the API profile name that should also be defined in '/resources/api.profiles.ini' file. This tells API what API profile (and thus what profile settings) the API will use when validating the API request.

Note that internal API requests - such as those made from Controllers internally - never need API validations as in order to execute a Controller method, the parent call already has to be validated.

This value is, by default, that of public API profile that is defined in configuration.

www-timestamp

If the API profile requires a timestamp validation, then this UNIX timestamp value has to be sent to API when making a request. API will then validate whether the timestamp was in the accepted age before executing the API call. There is more information on this variable in API Security documentation.

www-hash

This value is required by API if non-public API profile is used that requires hash-based input data validation. API will calculate it's own hash based on provided input data and secret key or session token and if the value of 'www-hash' does not match, then it returns an error. There is more information about this variable in API Security documentation.

www-ip-session

If this value is set, then the session token will be tied to the specific IP address where the request is made from. This is useful when it comes to protecting your session token. There is more information on this variable in API Security documentation.

www-session

This variable tells Wave Framework API to load session data from active session and apply it as input data for any API call. This is set to 1 by default, so session data gets always included, with the exception of Factory api() calls, which disable it by default.

www-crypt-input

This variable should hold encrypted data as a string that is sent to API. This data string should be encrypted as a serialized array and in Rijndael 256bit encryption, using secret key or session token as encryption keys. There is more information on this variable in API Security documentation.

www-json

It is also possible to send an entire JSON string to API that carries all of the input variables. API will first unserialize this string and then uses it as an input array.

www-jsonp

If this is set, then the entire output is wrapped within a method call as a function name with the value of this parameter. This is used for JSONP.

www-jsonv

If this is set, then the entire output is assigned as a JavaScript variable.

www-xml

It is also possible to send an entire XML string to API that carries all of the input variables. API will first unserialize this string and then uses it as an input array.

www-disable-callbacks

If this is set to 1, then any callbacks that have been set in the system will not be used. This allows to disable things such as redirects and other similar functionality, when it would otherwise be set through the Controller.

www-public-token

This is required if public API profile is used and the setting for 'api-public-token' in Configuration is set to 1. This means that it requires that a request token - used to protect against Cross Site Request Forgery - is set and is the same as the one stored in sessions. This is only required if you use sessions and store data in Wave Framework setUser() storage.

www-headers

If this is set to 1, then 'www-response-code' and 'www-message' response keys will be sent in headers instead. This allows the output data array to be 'cleaner', but requires the developer to test the existence of these values if they are important for the system. PHP API Wrapper supports this internally, but JavaScript API Wrapper does not.

www-version

If this value is set, then when the system attempts to load Models, Views and Controllers, then it attempts to seek them from a subfolder within /models/, /views/ and /controllers/ based on this value. If such a file is not found, then the system returns the core file.

API Output - Flags and Values

API will return whatever data controller returns and in a format that was defined in input of 'www-return-type'. But there are some Wave Framework specific values that can be returned together with the response and these values can be checked for things like errors and response codes.

Note that these values may not be present in the response, it entirely depends if the developer uses them. Most of the output flags and values will be removed entirely before output is returned to the user agent. The only exception is when an error occurs.

These are the values that may be found in the response from API:

www-message

This is a verbose message returned from API about whether the API command was successful or not. This is not translated and is language-independent. This can be hidden over HTTP API if 'www-headers' is sent as '1' with the request, which makes this value be visible only in HTTP headers.

www-response-code

This is response code from API. This value could be in 1XX namespace (for system and configuration and formatting errors), 2XX namespace (used by API Wrappers), 3XX namespace (used for custom developer defined error messages), 4XX namespace (used for negative and failed messages where error did not occur but the intended action did not happen either) and 5XX namespace (which is used for a successful response). There is more information on this in the Response Codes documentation. This can be hidden over HTTP API if 'www-headers' is sent as '1' with the request, which makes this value be visible only in HTTP headers.

www-token

This is returned if 'www-command' was set to 'www-create-session' and session token creation was a success. This carries the key that should be used for session token.

www-token-timeout

If session token was created, then this tells the user agent how long the session token is valid without timeout. Note that whenever a new request is made and the token has not timed out, then this timer is reset. This value is 'infinite' if token timeout is not set in the API profile.

www-ip-session

If the token creation was demanded to be IP-dependent, then this value returns the IP that is allowed to make the requests with this token.

www-disable-callbacks

This is similar to input flag, except this is sent from the Controller as a response and it will do the same thing: disable additional API callbacks, such as redirects or cookie-setting.

www-data

If Controller sends this variable, then all other return variables will be overwritten and this is used as the sole response variable instead. This is actually used by API when gathering response from output buffer instead of returned array.

www-timestamp

This is the timestamp of the moment the response was created. This can be used to validate response age by the user agent.

www-hash

This is a response validation hash that is generated from the response array and secret key or token. There is more about this variable in API Security documentation.

www-set-header

This string or strings from this array will be set as headers in response from API call.

www-set-cookie

This array will be used to set cookies in the response. It requires 'name' and 'value' keys in the array or sub-array (since multiple cookies can also be set).

www-unset-cookie

This unsets a single cookie or an array of cookies based on cookie name in the array of this value.

www-set-session

This array will be used to set session variables in the response. It requires 'name' and 'value' keys in the array or sub-array (since multiple session variables can also be set).

www-unset-session

This unsets a single session variable or an array of session variables based on cookie name in the array of this value.

www-unset-header

This unsets a single header or an array of headers based on the header name in the array of this value.

www-temporary-redirect

If this is set, then user agent is told to redirect to the value of this variable. This is for a 302 Temporary Redirect header.

www-permanent-redirect

If this is set, then user agent is told to redirect to the value of this variable. This is for a 301 Permanent Redirect header.

www-xml-namespace

This is a namespace parameter and URL that will be set for the XML, if XML data type is requested. Default is 'xmlns:www="http://github.com/kristovaher/Wave-Framework"'.

www-xml-root

This is the XML root node elements name if the output format is XML. This is 'www' by default.

www-xml-numeric

If this is set and the output format is XML, then numeric array entries will be set with this name in the output XML. By default it is 'node'.