Generic or Custom API, which one to use?

api-538x294

On the past month I was working in a project, that seemed to be easy on the beginning, to create a kind of service that should be the core to delivery coordinates and weather information of trucks, airplanes and ships from an specific company, and, the project has extended a little (as always), because the client also wanted to add some extra resources like user control, sell credits to use the service among other details. In fact, it wasn’t so easy as I expected but in the end, we did it.

Our team made some research before develop anything and concluded that an API should be the right service to complete this project.

An API is not just a JSON or XML content, it’s more than that, it can have many aspects and involve different types of access, depending of the needs, the most common types are the RESTFul service which is more like an architecture over HTTP using different methods to make the operations and the RPC (Remote Procedure Call) service which is usually done via POST method sending payload information to define the operations. It was important to us to know exactly what are the client needs and what we should start to use.

Knowing about these and some other dificulties of building a web service API, we did what any sane developer would do… search on internet for some basic and simple API to build over it our own solution. Well, we didn’t find something easy and simple, but we have found the Zend apigility which is a fantastic API-based architecture and is based on Zend Framework, so we just gave a chance for it.

ag-hero

The apigility tool offered a great tutorial, many sample codes and can be setup almost by the admin enviroment, also, a complete set of answer types, allowed methods, filters, validations and is also documentation ready, it’s really amazing.

intro-first-rest-service-status-settings

But, “with great power comes great responsibilities”. The apigility is based on Zend framework, so it’s implicit necessary to have a good knowledge on the framework to make  a good job, also, we don’t felt like this is the right solution for this project, it was more like “A cannon to hunt a little bird”, and more crucial, the Zend framework would push us to do extra documentation and can be a possible problem in future updates, for the client, as we don’t have too much professionals available with this knowledge. So, we give up of apigility for now.

After some long discussions, following the team instincts, feelings, making some sketches, we kept the idea of making by ourselfs a PHP web service API, which should exactly fit our needs without lack or overage of resources.

There is a lot of discussions around the API standards and if it should be adopted or not, among them are the swagger specification and the Open API Initiative which are supported by many stakeholders like Google, Microsoft, IBM, Paypal and other giants.

We didn’t followed all the standard specifications that we found, but we focused in almost all of them to finish our API.

Was it worth? Well, we were a team of 3 person, we planned, documented, developed, tested and done the service in about 5 days and the client is happy and the project is working, so, the team and the client thinks it was worth it, that’s what matters. 🙂

api-sample-use
Sample use of the tracking API

Elementary OS and the new About page

Reading about the new Elementary OS updates (the distro that I use) I saw the new “About” page which now have better looking than before.

elementary-about-page

But, that default mac computer icon does not fit my computer and as a thinkpad user I am would be proud if the Elementary OS detects my machine’s vendor name… but it’s not what happened. 😦

Following my wishes to have some custom information on that page, I made some research on the elementary code, on github and discovered that the “about” page can load information from an specific file on the computer, so I have try it and that what it looks like now:

Captura de tela de 2017-07-04 11.42.28

Here is how to do it:

  • Open as an Administrator the path /etc
  • Create a file called oem.conf
  • Add the following content on the created file and set your own information and icon:
    [OEM]
    Manufacturer=System76 Inc.
    Product=Meerkat
    Version=meer1
    Logo=/etc/oem/logo.png
    URL=https://support.system76.com

 

The Logo should be a transparent png file, so I used a very nice online tool on editphotosforfree.com to easily remove the background of an image that I found on google.

The descriptions of manufactures, product, version and the link of the URL can be anything that you want to show on the “About” page.