A Very Simple API 

development-api

There comes a time in the life of a developer where he/she is forced to deal with an API, be a desktop or a web developer, in some time it will be necessary.

hot-head

Also, maybe, the developer will need to create it’s own API and then is where the things get a little bit difficult. There is a lot of concerns, discussions and suggestions around API standards but none of them are still the definitive right way to build an API, so as always each developer builds the code as it wants.

For me, everytime that I need to deal with a webservice, I study a lot, check the new standards look at the client needs and make the best effort to make the most light and precise services that the client wants. But thats the hard way, the easy way should be, to unpack a generic API code adjust some settings and start to delivery services… Should be like this.

crazyHarry

There are some nice tutorials and tools on internet about building an API, like with laravel and with apigility, but almost all have some framework dependencies and then I though in something more simple, just with the basic stuff, why not?

 

Considering all that, and on all the effort spend on every new webservice, I decided to make a very simple API pack with the basics to make a webservice to work, so here is what I tried to covered:

  • Auto detect XML-RPC or REST request;
  • Standard formated XML or JSON automatically (depending of the request);
  • Automatic deal with errors and/or warnings (saving in a log);
  • Resources to return standard field answers on requests;
  • Code injection protection;
  • Method request control and run according to the operation method request (POST, GET, PUT, DELETE, OPTIONS, PATCH);
  • Versioning control;
  • URL friendly following at least level 2 maturity level;
  • Start point to build my own custom webservice methods;

It’s not easy to cover all the resources of an API and still keep the code simple and dependencies free but I tried. In the end the result was very good but still have some work to do.

The code is avalibale on my github account and it’s free to use and to contribute. Note that this is not the “state of art” and any kind of contribution will be welcome.

The very simple API pack worked just fine and  can be used on every new project with just a few lines of set up on an specific settings file. Also, the use is very simple:

  1. Extend the main class AbstractService:
    class MyServiceName extends \classes\AbstractService
  2. Initialize the service with the needed settings:

    public function execute()
    {
    $this->initialize(['allowedMethods'=>[AMT_GET, AMT_POST, AMT_OPTIONS],
    'answerType'=>AST_AUTO]);
    }
  3. Add the code on the respective method and call the answer method:

    public function onPost()
    {
    //... your code here
    $this->answer([
    'message' => 'Here are the fields that the API received',
    'fields' => $this->getFields()
    ]);
    }
  4. Call the API from the browser:
    http://your-server-path/v1/MyServiceName

… and voilà!

vsapi-sample-answer
Sample JSON answer using AJAX on vsapi

Also, an error message:

vsapi-sample-error-answer
JSON error answer using AJAX on vsapi

And, a XML answer:

vsapi-xml-answer
XML answer using PHP on vsapi

Wireframing Before Code

Starting a new software project is not an easy task for anyone, specially if you have a great imagination and some coding habilities. Sometimes the process of creating a simple app or utility can become a big and infinite nightmare with endless resources and pending ideas if it is not very well planned.

Among the traditional steps of documentation of a software project I usually like to start with the wireframing step (or sketch as some people like to say), where turns it possible to see how the final product will looks like and also bring some insights about the resources that need to be planned on the tasks. This kind of effort can save a lot of time, believe.

boogle-sketch

When wireframing the screens of the project is possible to see some options and some limitations that you only would remember when you see the final product. Also, this effort makes the process of filtering bad ideas that seemed to be good on your mind but did’t going well when applied.

bad-sketch-sample

There is not a standard way for wireframing, it is just a way to put your ideas and thoughts in a way that you and your coworkers can see what you are thinking to do. Follow some design patterns (mobile-patterns, pttrns) are a good choice if you dont know where to begin.

As wireframing is not a trivial task for me, and I just do it when start a new project, I don’t have a favorite app to do this, instead of that I always make a search on internet an find what is trending. On my past project I found the mockflow web app which is a very complete tool with a lot of resources and also have components that are similar to those used on developing, like: bootstrap, htm5, android, iphone, etc.

Mockflow is a paid app and also have a free version, which is limited by the number of pages that you can add on the wireframe project. For a free version is good enough.