If you are a content provider, you have probably been asked this question by your partners:
Do you have an API? And what can I do with it?
APIs have become the norm in modern systems. The need to syndicate data to customers, vendors and different parts of your application have made APIs an essential part of your business.
Many of our customers rely on APIs to do the majority of their business. As an example: A major bank uses an API to produce all of its loan application documents.
If you are new to the API world and wondering why you need one, please read on as we introduce you the concept of SOA (Service Oriented Architecture) and try and answer some of the basic following questions:
- What is an API?
- How can you syndicate content from your application across multiple channels?
- How can your website, mobile application, desktop application and content partners interact with your system?
- What are the most common data formats produced and consumed in today’s APIs
- Should you use REST, ODATA, JSON, SOAP, XML, RSS or ATOM?
Let’s start with SOA
Service Oriented Architecture or SOA for short is a system architecture that exposes components of your system as a service to other components. Communication between components is done over the network using common protocols and is technology independent.
You can host your service in the cloud and allow consumers running a web page to access it from a browser, or you can host it inside your DMZ network and only allow users from within your internal network to communicate with it.
To design an SOA system means to expose almost every aspect of your system as such a service. For example: let’s say you want to add a new customer. You design a space in your data store for customers, then build a service that can communicate with the outside world.
Now, anyone with access can perform that action – i.e. take advantage of that service – from within their own applications. Of course, you wouldn’t want just anybody to have access, or the ability to add customers to your system. You will probably want to restrict that ability to your main website, and maybe some lead collecting affiliates.
Let’s list all of the services needed to read and update your customers, group them together and call them your customer Application Program Interface or API for short.
Your API will contain the full list of all of your services.
What is an API?
An API is a set of routines that expresses a system in terms of its operations, inputs, outputs, and underlying types. An API defines functionalities that are technology independent, allowing API consumers to relay on standards in order to communicate with it.
Your customer API is a part of your overall API and will expose the application’s functionally related to customers. Your overall API is the sum of all API groups, and exposes all of the services needed to power the application.
An API can be private or public and can power internal or external systems.
To build such services and make sure they can be considered a full API you need to think about the following main three points:
Or FCA for short.
XML based formats include Plain XML, SOAP, RSS and Atom.
SOAP (Simple Object Access Protocol) is the most commonly used and most effective protocol of all the XML based protocols. SOAP based services include a WSDL (Web Service Definition Language) file describing the information passed in the service and allowing for object generation by your favorite IDE in most software languages.
Since most programming languages are OOP (Object Oriented), generating objects from a WSDL is essential for rapid development while producing and consuming SOAP services.
Plain XML services require you communicate via POST or GET of a simple XML in a form of text. Such services will usually require documentation describing the XML tags needed to use it, and will often offer an XSD (XML Schema Definition) file, describing the shape of the XML and allowing IDEs to create objects that serialize (translate) into the service’s data structure.
RSS and ATOM are both simple syndication protocols and are intended to mainly be used by RSS readers, such as your email client. Even though they are technically considered a service, they do not allow any updates to be made and therefore cannot really be considered an API.
As technology progressed, the original JSON standard was enhanced so that it could be consumed across domains by adding a “padding” callback function, attaching the remote data to an HTML page as a simple script “include.” This way, the function could be executed when the data arrived, processing it asynchronously and immediately showing the results on the web page. This improvement (“JSONP”) allows your API servers to reside on a dedicated API domain (for example: http://api.MyCompanysWebsite.com) while your website still resides on the traditional http://www.MyCompanysWebsite.com domain. This breakthrough was the beginning of the JSONP revolution.
As a result, JSON is generally the preferred format for new HTTP/HTTPS APIs, due to its flexibility and small size, while SOAP remains a good choice for limited APIs that are consumed by server to server in binary form.
JSON can also be represented in binary form. Binary JSON is called BSON and is mainly used in No SQL databases as a form of data storage.
You have probably heard the term REST before. What is REST and how can we use the REST convention in order to consume an API service?
Representational State Transfer (REST) is a set of HTML standards that defines HTTP verbs and URLs that are commonly expected to be employed to handle an API operation.
For example: A REST interface expects that when you call a service over HTTP with a GET verb (typing a URL into your browser is a GET operation), the service will perform a read operation and return the data to you.
Calling a service with a POST operation, as when submitting a form, will perform an Insert operation within the service. Deletes and updates will be performed by HTTP DELETE and HTTP PUT calls respectively.
In addition, URLs can be used in order to perform CRUD (create, read, update and delete) operations.
REST employs other conventions, to make code clearer. For instance, if your service will be running at: http://MyCompanysWebsite.com/resources/ item 17 should be available at the URL http://MyCompanysWebsite.com/resources/item17, and will respond to predictable HTTP calls in order to manipulate its state.
A step up from REST is ODATA (Open Data Protocol).
OData is a RESTful data access protocol initially defined by Microsoft. Versions 1.0, 2.0, and 3.0 were released under the Microsoft Open Specification Promise.
Version 4.0 was standardized at OASIS (Organization for the Advancement of Structured Information Standards).
In addition to the standard REST protocols, ODATA also defines additional features such as pagination, filtering, and other useful data manipulation functions. It’s useful when its important to be able to have greater control over how data is presented to the user.
The complete ODATA protocol specification is available at http://www.odata.org
When APIs were first developed, security was limited to a user name and password being sent with each request.
Sometimes an API key was required, and served as a role based authentication. A caller would send its login and key, and the API would verify that a caller’s login is valid and that the key had permission to access the service.
User authentication was done either at the server level or the application level, while API key verification was always done at the application level. Today, as APIs have matured, we generally use OAuth2 to secure them.
We should mention that Authentication is just a small part of securing your API. Authentication deals with access control.
It does not cover message confidentiality and other security vulnerabilities that can stem from faulty code or infrastructure.
Internet communication security is a vast subject and here at Inverted Software, we are experts at building secure systems that comply with the strict OWASP (The Open Web Application Security Project) standards.
Before we begin our review of Authentication methods, we will highly recommend you protect traffic confidentiality by using a Public Key Infrastructure (PKI) issued X.509 certificate.
Public Key Infrastructure (PKI) is a system of certification authorities (CA) that verify and authenticate electronic transactions through the use of public key cryptography.
X.509 certificates is more known as an SSL certificate. X.509 certificates are stored within a certificate store. A computer running Windows has several kinds of certificate stores, each with a different purpose.
In a basic authentication, a client establishes a connection with a service. The client needs to “trust” the X.509 certificate presented by the service. Then a secure network connection can be established. The client then passes a user name and password in the request to the service. The credentials are passed in the request headers.
Basic authentication must be enabled on the server. As the server accepts the request, it will check for a valid user. If authentication has succeeded, it will allow the request.
OAuth is an open standard for authorization. OAuth provides client applications a ‘secure delegated access’ to server resources on behalf of a resource owner. This means that instead of passing user names and passwords in each request we can log in once and get a token. We can then save the token and send it with each request until it expires, usually within fourteen days. When the token expires, we can just renew it and continue making requests to the service.
If you have ever allowed a Facebook application access to your account in order to run it, you have used at least a part of OAuth.
Another way to secure your API is SAML (Security Assertion Markup Language). SAML is a product of the OASIS Security Services Technical Committee and was designed to address web browsers’ Single Sign-On (SSO) needs. It was adopted for API security in limited form, and is commonly being used to secure SOAP services.
Designing a good API using FCA can allow it to be used by multiple consumers. Your website can consume it using server to server or client to server calls, a mobile application can consume it from users remote phones and your partners can consume it with their own applications.
But designing a secure, robust, and usable API requires some thought about the intended use – who will consume it, what will they need to do, and how secure does it need to be. Fortunately, APIs have been evolving for years, and there are generally good tools available to do the things you need to do – allowing you to create a safe and reliable system, without having to reinvent the wheel.
At Inverted Software, we build APIs for new and existing systems in a wide variety of industries. If you have an API to be built, or consumed – or just want to bounce ideas off of someone – contact us at firstname.lastname@example.org to discuss how we can help.