What is an API

API stands for application program interface. In a nutshell an API is a way for external applications to access information and queries from your program. Twitter for example has a a REST API that allows you to access all types of data from twitter. REST API’s are among the most common types of APIs. A REST API allows you to make requests using standard http methods. You can make a GET request to get data, POST request to insert data, PUT request to update data, and DELETE request to remove data. Most companies give a limited number of free API calls into their applications. As your need for their APIs increases they start charging more for API calls. A call is counted each time you call an endpoint. When a company limits their endpoint requests you can be smart and request more data through a single endpoint query.

I have a good example of working around limited API calls. Salesforce is the worlds leading CRM and they have an open api you can use to access data, however, they severely limit the number of times you can call an endpoint in their system. I have worked for companies that interface for Salesforce and we needed to get Lead data from them. Instead of calling an http GET endpoint to get each lead individually we would query as many as we can and just store them on a local server. Another thing we did to limit our endpoint calls was to batch process them. We would store all the information we needed to access and then every 15 minutes or so make batch queries. This limited the number of queries we needed to call by about 70%.

Why an API

There are several reasons large applications should use an API as one of their layers of abstraction. An API is not the same thing as a plugin or an application, but the business models are similar. One reason the iPhone became so successful is because by the third generation apple introduced the app store. Salesforce generates revenue for so many people by allow apps or plugins to be installed on their application from third parties. An API is the same idea. You want to have people be able to access, share, and improve your software by any means. The following are just a few highlighted reasons for having an API built into your application.

• Separation of functionality. A programming concept any software engineer should know well is the separation of functionality. You want your user interface, persistence, and user/business logic to be in separate layers. PHP has been notorious for making it easy to violate this idea. So many php applications have their user interface, persistence to sql, and other user logic all in the same class. By making an API and having your own application access it for data helps separate the parts of your program.
• Easily access application on multiple devices. This is probably the biggest reason to have an open API. Say for example you are making some type of SAAS application. About half of all web traffic is through high end mobile devices today. If you build your application and it’s just for a desktop you are losing lots of potential clients and traffic. By having an API you can make your desktop website UI and IOS or Android mobile application call into the same API. This means that you can make as many UI’s as you want and not have to rewrite the persistence layer or business logic for each application.
• Makes you money. As we mentioned before, most large applications have some type of an api available to people for free, but it’s limited. Some companies can make a lot of money through their APIs by charging for high usage. Having an API for your application means you can earn money from people who will want to access it directly.
• Allow other people to access and contribute to your data. A good API makes your data collection bigger because people will be contributing information to your database. We live in an age of big data. The more data you have the more you can mine it. Data mining is seriously awesome and can also contribute to making more money. For example you can take customer information and show based off of input information if they are likely to buy your product or not. You can even take it a step further and determine what would be needed to most likely close deals.

Various examples of how to build an API

Ultimately if you decide to add an API to your business application you need to do what is best for you and the company who owns the application. If you wrote all your business logic in PHP there are some great rest frameworks for doing a PHP REST API. If you have your business logic in C# then that is what you should use to program your API endpoints. The following are just a few of the industry leading frameworks for making an open REST API.

• Javascript Node. I have not always been a fan of javascript, but node has been kicking ass with Express. Express is a very easy framework for making a REST API. PayPal made the conversion from Java to Node and here are the measured response time differences. Another thing I have come to love about using Node with Express is the amount of lines of code I need to use. I made a simple recipe application. One backend was in Spring and the other used Node’s Express. The total number of lines in the Spring application was about 3000 and the total number of lines in Node’s application were about 300. Spring requires a lot more verbosity because all DTO (data transfer objects) have to be defined – even when using a noSql persistence layer.
• Java Spring. Even if I am slowly being convinced of how awesome NodeJS is a lot of places still use Spring or are in the process of converting to spring. Spring has a REST Client  framework that makes creating a rest application super easy and simple. Spring is all in Java and with that you can write your application in either Scala or Groovy too. I still love the Java language and Spring takes out so much verbosity in building an API.

There are plenty of examples in both node and spring on how to build an API. The body of the requests is most easily done using JSON, but XML or plane text can also work. Just remember that best practices dictate the following REST requests.

• GET is used to get data from your application. Use this for a single object or a list of objects to return.

  • GET: www.domain.com/api/object/id

• PUT requests are used to upsert data. If data doesn’t exist it creates it, and if it already exists it will update it.

  • PUT: www.domain.com/api/object
    BODY: { "id":"12345", "foo":"bar"}

    • This example takes an id should find the ID in your database and update the field “foo” and set the value of “bar.” Normally you return the full object with the id. If there is no object the response will return the id of the newly inserted object.
• POST http request is used to create a new object.

  • POST: www.domain.com/api/object/
    BODY: {"name":"Bilbo Baggins", "age":"111","race":"hobbit"}

    • This type of request should insert a new object into the database for Bilbo Baggins and the response should return either the full object or just the ID of the newly inserted object.
• DELETE removes the persistence of the object – deletes it from the database or adds a ‘deleted’ attribute to the entry in the database. Big data never really should delete date, only insert and modify it.

  • DELETE: www.domain.com/api/object/id

• OPTIONS are used to get the available list of options you can use with a method or object.

There are other types of http requests that you can use in your rest application, but these are the most common. I have seen applications where you go to delete the object and you did a post with a JSON body that said delete = true. This is terrible! You should simple just use http DELETE to  api.application/object/id in order to remove an object. Using the HTTP standard requests will actually save you network traffic as the scope of what is carried in them is limited to the function they are performing. This is great when you make a mobile application and all data being transferred is precious.