In order to identify your account, you have to provide the domain name of your organization. I will demonstrate how to create an account using the “ws.dimuthu.org” as my domain name.

1. First go to http://governance.cloud.wso2.com from a web browser and click the ‘Register’ button. You will be asked to enter the domain name as the first step.

Enter the domain

After that, you have the option of validating the ownership of the domain right at the registration process, or you can skip the validation and continue to the next step in which case your domain will be appended ‘-trial’ suffix. You can validate the ownership of the domain later at any stage.

Here I want to validate the domain right now, so I click ‘Take me to the domain ownership confirmation page straight-away’ and click the ‘Submit’ button.

2. This will redirect you to the domain ownership validation page. You can validate the ownership of your domain in one of two ways.

Method i). Just create a text file named ‘wso2gaas.txt’ in the web root of your domain and enter the given text. This is the most simplest method of two.

Validate domain name using Textfile

Method ii). You can put a DNS entry according to the given instructions. This is a little tedious approch to validate the domain. In fact it may take a while to propagate the new DNS information, so you may have to wait hours without refreshing the page until you finally validate the domain ownership.

Click the continue button after the domain validation done. Then you will be redirected to a page requesting more information.

3. Tenant Registration Page

Tenant Registration

4) After this step, you will be notified to check for your email which will contain a mail with a link to proceed with the registration. There you will be able to select a theme for your organization and finalize creating your account. Login to the admin account for your tenant with the credential you provided a the time of the registration.

The domain ownership validation was introduced to WSO2 Governance as a Service account registration only now. So for organizations who have already have account will have a message similar to this when they are trying to login to their account.

Info box at login

So the account I have registered using the domain name ‘example.com’ has been renamed to ‘example.com-trial’. As the instruction of the message says you can go to the account management page after the login and validate the domain ownership.

Account Management Page

The book “RESTful PHP Web Services‘ by Samisa Abeysinghe certainly fill this gap. It can be used as a step by step guideline for newbies to learn the concepts and write simple RESTful PHP applications and Mashups. And even experienced developers would find this a great reference to keep nearby while working with RESTful Web Services in PHP. And it has lot of code samples, utility functions that developers can use it in their applications.

About the Author

Samisa Abeysinghe is a well recognized name in the web services world. He lead the development of Apache Axis2/C and WSO2 WSF/PHP, two famous open source web service frameworks for ‘C’ and PHP. In addition to his deep knowledge in the subject, his experience in involving with the community and the enterprise for years and working as a lecturer in universities, should have influenced a lot in writing this book.

The Arrangement and the Content

The arrangement of the book is done really well to make sure the reader can go through it in the right sequence. All the content is bundled just within 200 pages. So you don’t need to allocate a lot of time to go through the whole book. It is organized into 7 chapters and two appendixes which are mostly independent from each other.

The first chapter is completely devoted to explain the concepts of RESTful web services. It basically explains what is RESTful web service and why it is needed. And it briefly mentions about the currently available REST Frameworks for PHP.

The second chapter introduce some PHP codes that do REST web service requests and handles the XML responses using both DOM and SimpleXML APIs. And in the third chapter it shows more code samples specially about consuming real world web services like BBC, Yahoo and an earthquakes information service. Theses codes are written as mashups mostly combining two services to produce more meaningful information.

The forth chapter is about  designing and writing web service providers. Its counterpart, writing web service consumers is described in the chapter five. There it demonstrate a library system that operate using RESTful webservices. You can map this example to any system that you may like to develop to run with RESTful web services. The chapter five of the book is available as a free download, RESTful PHP Web Services – Chapter 5.

The forth and fifth chapters are not using any framework to write the sample codes on consuming and providing web services. But in the sixth chapter it shows the use of Zend framework to do write them. There it rewrites the same example (The RESTful library system) in MVC (Model -View – Controller) approach using the functionalities of Zend framework. (In fact the View in the service is omitted).

The seventh chapter is about debugging web services. Debugging is a much needed step in any software development cycle. So if you are a newbie, you should read this chapter before start writing any of your own code. This introduces tools and methodologies to make your debugging easy and effective.

The book contains two appendixes. They are too really useful as the chapters of the book. In the first appendix it explains another REST web service framework, WSO2 Web Services Framework for PHP (WSF/PHP). To demonstrate it uses, some selected functionalities of the example library system (that is mentioned in chapters 4, 5, 6) is re-implemented using WSF/PHP. And it shows you how you can convert this RESTful system to a SOAP system in a minute. The second appendix provides you a code of a class (RESTClient), that you can use in consuming web services very effectively.

Recommended Readers

This book assume you have some knowledge in PHP. But it doesn’t require you to know anything related to web services, REST or XML. As you read the first few chapters, you will have a good understanding on the concepts and the basic applications of REST and XML using PHP. And the later chapters will guide to get deeper knowledge in writing complex and real world applications.

If you are a professional developer, you can skip the introduction chapters and jump directly to where you need to refer. For an example, if you use this book as a reference in designing and developing RESTful web service providers, you can directly read the chapter4 – Resource Oriented Services, chapter6- Resource Oriented Clients and Services with Zend Framework and probably the chapter 7 – Debugging Web Services.

This book contains the same example system (the library system) written in three different approaches, first without using any framework support, second using the Zend Framework, third using WSF/PHP. Each of them has its own pros and cons. So if you want to determine the approach more suitable to your requirements, or thinking of migrating from one to another, this book will be an ideal resource for you.

As you may have already noticed, this book contains lot of code samples. All the concepts are followed by simple code samples that explain the concept. In appendix it gives you a complete code for RESTClient class that you can use to call any REST service. Apart from the code of the example library system written using different frameworks, it has lot of codes for calling public web service APIs. And the explanation of the code is also done really well.

So it is clear this book is more targetting readers who like to implement PHP RESTful Systems in practice. And it covers enough concepts that you needed to know in writing practicle applications. So this book can take you from the zero knowlege to a deeper knowlege of RESTful PHP Web Services.

So if we rewrite the RESTful Demo (Written in PHP) using Axis2/C, the services.xml would be something like following.

<service name="RESTfulSchool">
    <!-- mentioning the service library-->
    <parameter name="ServiceClass" locked="xsd:false">RESTfulSchool</parameter>

    <!-- some description -->
    <description>
        The RESTful School demo
    </description>

    <!-- list of operations -->
    <operation name="getSubjects">
            <parameter name="RESTMethod">GET</parameter>
            <parameter name="RESTLocation">subjects</parameter>
    </operation>
    <operation name="getSubjectInfoPerName">
            <parameter name="RESTMethod">GET</parameter>
            <parameter name="RESTLocation">subjects/{name}</parameter>
    </operation>
    <operation name="getStudents">
            <parameter name="RESTMethod">GET</parameter>
            <parameter name="RESTLocation">students</parameter>
    </operation>
    <operation name="getStudentInfoPerName">
            <parameter name="RESTMethod">GET</parameter>
            <parameter name="RESTLocation">students/{name}</parameter>
    </operation>
    <operation name="getMarksPerSubjectPerStudent">
            <parameter name="RESTMethod">GET</parameter>
            <parameter name="RESTLocation">students/{student}/marks/{subject}</parameter>
    </operation>
</service>

We will check how to write the service logic for a operation like “getMarksPerSubjectPerStudent”.

axiom_node_t *
RESTfulSchool_getMarksPerSubjectPerStudent(
    const axutil_env_t * env,
    axiom_node_t * request_payload)
{
    axiom_node_t *student_node = NULL;
    axiom_node_t *subject_node = NULL;

    /* Extracting out the child nodes from the request */
    student_node = axiom_node_get_first_child(request_payload, env);
    subject_node = axiom_node_get_next_sibling(student_node, env);

    /* now we can write the logic to retrieve the marks
       for the given student and subject and build and
       return the response payload */

    return response_payload;
}

As you can see the variables {student} and {subject} given in the services.xml can be easily accessed from your business logic, so we can build the response accordingly.

This way you can build a RESTful web services easily using C language.

But there may be situations that you can’t use the codegen tool to get your work done. May be you don’t have a WSDL. Or codegen tool fails generating code for you WSDL (very few chance .

In these situations you have to go to writing the complete service manually, I.e. You will write the code for the business logic + Axis2 Skeleton (code to plug the service logic to axis2/c).

Axis2/C service consists on:

• service.xml – Simple way to describe the service and operation. (Far simpler than a wsdl)
• Skeleton – c pseudo class inherited from axis2_svc_skeleton
• Service logic – You service logic per service operation

services.xml

This contain the name and some description of the service, the name of the .dll (in windows) or .so (in linux) to load the service and list of operations with their parameters.

E.g.

<service name="echo">
  <!-- dll or so name of the service -->
  <parameter name="ServiceClass" locked="xsd:false">echo</parameter>
  <description>This is a testing service, to test whether the system is working or not</description> 

  <!-- list of operations -->
  <operation name="echoString">
    <!-- addressing information for the operation-->
    <parameter name="wsamapping">http://ws.dimuthu.org/axis2/echoString</parameter>
  </operation>
</service>

In addition to shown ones, there are a bunch of parameters available to customize your service. Visit Axis2/C manual for more.
Skeleton
This is the code that form the dll for your service. At least you should implement the following set of functions there.

• Required function to create any axis2/c DLL
  • axis2_get_instance – Call at the creation of the DLL
  • axis2_remove_instance – Call at the removal of the DLL
• Functions to be implement the axis2_svc_skeleton interface (sorry I’m using the java jargons)
  • init- Initialize the service (execute per start of the server)
  • invoke – invocation of the service (execute per each client request)
  • on_fault – invocation of the fault (execute if invoke returns NULL with error set)
  • free – Freeing the service (execute per stop of the server)
• In addition to these mandatory functions I will be using axis2_echo_create to create the service skeleton for the echo service.

I will start with showing the structure of the service skeleton functions first.

/**
 * echo free method
 */
int AXIS2_CALL echo_free(
    axis2_svc_skeleton_t * svc_skeleton,
    const axutil_env_t * env);

/**
 * echo invoke method
 */
axiom_node_t *AXIS2_CALL echo_invoke(
    axis2_svc_skeleton_t * svc_skeleton,
    const axutil_env_t * env,
    axiom_node_t * node,
    axis2_msg_ctx_t * msg_ctx);

/**
 * echo init method
 */
int AXIS2_CALL echo_init(
    axis2_svc_skeleton_t * svc_skeleton,
    const axutil_env_t * env);

/**
 * echo on_fault method
 */
axiom_node_t *AXIS2_CALL echo_on_fault(
    axis2_svc_skeleton_t * svc_skeli,
    const axutil_env_t * env,
    axiom_node_t * node);

Note that you have the freedom to give any name to each of these function. In fact you should give a name with your service name as the prefix to avoid name conflicts. Then you can specify service skeleton to take these functions to represent to init, invoke, on_fault, free methods using the following code.

/**
 * you should specify your functions set exactly in the order
 * init, invoke, on_fault, free
 */
static const axis2_svc_skeleton_ops_t echo_svc_skeleton_ops_var = {
    echo_init,
    echo_invoke,
    echo_on_fault,
    echo_free
};

/**
 * Create function
 */
axis2_svc_skeleton_t *
axis2_echo_create(
    const axutil_env_t * env)
{
    axis2_svc_skeleton_t *svc_skeleton = NULL;
    /* Allocate memory for the structs */
    svc_skeleton = AXIS2_MALLOC(env->allocator, sizeof(axis2_svc_skeleton_t));

    /* you give the function pointers array to the ops of the skeleton */
    svc_skeleton->ops = &echo_svc_skeleton_ops_var;

    svc_skeleton->func_array = NULL;

    return svc_skeleton;
}

So you create the service skeleton for your echo service inside the axis2_echo_create function. In fact you need to call this function from the DLL creation function (i.e. ‘axis2_get_instance’ funciton). And in the ‘axis2_remove_instance’ function you call the macro AXIS2_SVC_SKELETON_FREE which in fact call the echo_free function to free the resource at the removal of DLL. Here are the implementation for the DLL creation and removal functions in this particular service.

/**
 * Calls at the creation of the dll.
 */
AXIS2_EXPORT int
axis2_get_instance(
    axis2_svc_skeleton_t ** inst,
    const axutil_env_t * env)
{
    *inst = axis2_echo_create(env);
    if (!(*inst))
    {
        return AXIS2_FAILURE;
    }

    return AXIS2_SUCCESS;
}

/**
 * Calls at the removal of the dll.
 */
AXIS2_EXPORT int
axis2_remove_instance(
    axis2_svc_skeleton_t * inst,
    const axutil_env_t * env)
{
    axis2_status_t status = AXIS2_FAILURE;
    if (inst)
    {
        status = AXIS2_SVC_SKELETON_FREE(inst, env);
    }
    return status;
}

Up to this, it was all about preparing the service skeleton, So where you put your business logic?.

Service logic

Just create a function with the following format.

axiom_node_t *axis2_echo_echo(
    const axutil_env_t * env,
    axiom_node_t * input_node) {

    /* Write your business logic Right Here */
}

Here you extract out the input parameters from the the input_node and build the return node based on your output parameters. (Note that even though this is an echo example you can’t return the same input node as the output node, instead you have to replicate the input node and return it to avoid the double freeing)
Since this particular example you only have one operation you can call your business logic right inside of your echo_invoke function. But it doens’t work for cases where multiple operations present. Here is the right way to do it.

/*
 * This method invokes the right service logic
 */
axiom_node_t *AXIS2_CALL
echo_invoke(
    axis2_svc_skeleton_t * svc_skeleton,
    const axutil_env_t * env,
    axiom_node_t * node,
    axis2_msg_ctx_t * msg_ctx)
{
	axis2_op_ctx_t *operation_ctx = NULL;
	axis2_op_t *operation = NULL;
	axutil_qname_t *op_qname = NULL;
	axis2_char_t *op_name = NULL;

	/* logic to get the op name from message context */
	operation_ctx = axis2_msg_ctx_get_op_ctx(msg_ctx, env);
	operation = axis2_op_ctx_get_op(operation_ctx, env);
	op_qname = (axutil_qname_t *)axis2_op_get_qname(operation, env);
	op_name = axutil_qname_get_localpart(op_qname, env);

	/* compare it with our operation name, this is useful when
	   there are multiple operations exist */
	if (op_name)
	{
		if (!axutil_strcmp(op_name, "echoString"))
		{
			return axis2_echo_echo(env, node);
		}
	}

	/* set error in the failure path */
	AXIS2_ERROR_SET(env->error, AXIS2_ERROR_OP_NAME_MISSING, AXIS2_FAILURE);

	/* log the error */
	AXIS2_LOG_ERROR( env->log, AXIS2_LOG_SI, "op name %s is not known", op_name);

	return NULL;
}

So that’s the part you write the code. Compile the code linking necessary libraries in the lib directory of your axis2/c pack and don’t forget to include the necessary axis2/c headers.

• Necessary libraries for linux (Note: Some libraries are not directly called from your code, but it s better link all as some systems may complain about missing symbols in run time)
  • libaxutil.so
  • libaxis2_axiom.so
  • libaxis2_engine.so
  • libaxis2_parser.so
  • libpthread.so
  • libaxis2_http_sender.so
  • libaxis2_http_receiver.so
  • libguththila.so
• Necessary libraries for Windows
  • axiom.lib
  • axis2_engine.lib
  • axis2_parser.lib
  • axutil.lib
• Necessary header files (for both windows and linux)
  • axis2_svc_skeleton.h – To create instance of svc_skeleton
  • axis2_msg_ctx.h – Required in retrieving the dispatched operation name

If you follow this post up to now, this is the time you deploy the service with Axis2/C. Create a directory called ‘echo’ inside the services directory of axis2 repository (the root directory of you put axis2/c binary) and copy the services.xml and the dll in to that. (The DLL should be in the name echo.dll or libecho.so, if you change the dll name you should update the services.xml “ServiceClass” parameter).

Start the axis2 simple server (which is located in the <axis2_c_repo>/bin) and you are done. Your service will be deployed in “http://localhost/axis2/services/echo”. Use this endpoint to access your brand new service.