XINS Protocol
   Next

XINS Protocol

Anthony Goubard

Table of Contents

Introduction
Input requirements
Output requirements
Default error code
Conventions
Examples
Successful result
Unsuccessful result

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.

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