XINS Protocol
   Next

Introduction

This document describe the requirements to write a XINS compliant API.

Input requirements

XINS is a framework for invoking functions remotely using HTTP.

  • HTTP GET must be supported

  • HTTP POST must be supported

  • The query must have a _function parameter which is not empty and which contains the name of the function invoked. If this parameter is missing, or has an invalid value, or the value is not a name of a defined function, a HTTP 404 code must be returned.

  • If a parameter is sent without value, it should be considered as missing.

  • The framework should fail if the query has a function parameter with a different value than the one for the _function parameter.

Output requirements

XINS returns an XML document as output.

  • The root element of the returned XML must be result.

  • If a result code is returned, the result element must have a errorcode attribute.

  • If the result element doesn't have any attributes, the result is considered as successful.

  • Returned parameters should be returned with sub-elements <param name="name1">value1</param>.

  • The returned XML may contain a data element with sub-elements.

  • If some parameters are missing or the value of a parameter does not match the type, an _InvalidRequest error code should be returned.

  • If a generic error is generated in the implementation of the function an _InternalError error code should be returned.

Default error code

XINS includes standard error codes for common errors.

  • _InternalError

    This error code is returned when the implementation of the function has thrown an error.

  • _InvalidRequest

    This error code is returned when the given parameters do not comply with the specification of the input. The cases where this could happen is when a required parameter is missing, the value of a parameter does not match the type or the combination of a param-combo set in the specification.

  • _InvalidResponse

    This error code is returned when the returned parameters do not comply with the specification of the output.

  • _DisabledFunction

    This error code is returned when a function has been disabled. You can only have this error code if the framework has implemented the _DisableFunction (and _EnableFunction) meta function.

For more information about what the elements should contain when a standard error code is returned, look at the examples.

Conventions

Result codes, function names and parameters starting with an underscore are reserved for XINS.

  • Result codes are written with the hungarian convention and starting with an uppercase (e.g. DisabledAccount).

  • Function names uses the hungarian convention and starting with an uppercase (e.g. CheckMIP15, GetSessionDetails).

  • Parameters for the request are in lowercase (e.g. zipcode).

  • Returned elements and attributes are in lowercase. e.g.

    <?xml version="1.0" encoding="UTF-8"?>
<result>
  <param name="csr">anne8</param>
  <param name="loggedIn">false</param>
  <data>
    <property name="upgrade" value="true" />
  </data>
</result>

  • Returned parameter names use the hungarian convention starting with a lowercase (e.g. loggedIn, mainAccount, accountID).

  • The values of the parameters or of the attribute values for the data elements can be anything you want.

   Next
   Examples