Comprehensive Introduction into the World of APIs

You've likely come across the term 'APIs' countless times, but you do not know what they are and why they matter. In this article, we will delve into the world of APIs, exploring their definition, components, and the process of API integration and looking at some amazing APIs from Hydrogen.

To avoid further confusion and technical ambiguity, this article will help you understand the following:

1. Quick overview of APIs

2. Integrating with an API

3. Sample API Request with Hydrogen API

Overview of API

An application programming interface, mostly referred to as an API is an interface that enables that acts as a bridge to enable seamless interaction between different applications and data sets. Simply put, it allows you to communicate with other applications and data sets so you can take certain actions.

When an application decides to share resources with external applications, it exposes API endpoints. These endpoints can be consumed or queried by other applications to access shared resources or services. APIs are responsible for the smooth operations of popular websites, mobile apps and several other applications across the world.

For example, Google Maps has a total of about 13 APIs with several endpoints to power its Maps, Routes and Places features effectively.

“URLs are to WEBSITE, just as ENDPOINTs are to APIs” - Kolapo Imam

Hydrogen Payment Gateway for example helps businesses and organizations expand capabilities by enabling seamless payment collection via card, account-to-account transfer and several other amazing features.

Components of an API

This section of the article takes a deeper look at some of the basic elements that make an API request and response.

1. Endpoints: These are URLs that point requests to the API, similar to how every URLs functions on the server. At Hydrogen, you will often come across the endpoint URL for QA and another for PROD or LIVE. For example, to initiate payment with Hydrogen, you will engage the endpoint URL: https://api.hydrogenpay.com/bepay/api/v1/merchant/initiate-payment

2. HTTP Methods: These are actions that instruct the API request on what action to take when communicating with the server. The commonly used methods for Hydrogen are:

• POST: Sends information to the server, such as creating a payment request.

• GET: Fetches data from the server, such as querying the list of virtual accounts generated.

3. API Parameters: API requests and responses use different types of parameters and they are explained below.

• Header Parameters: These parameters are important for housing authorization tokens or subscription keys for API requests. For example, the header parameters of an API from Hydrogen will include an authorization token.

• Body Parameters: These are details that are included in the body of an API call when making a POST request and they are usually in JSON format. For example, when creating a request to initiate a payment with Hydrogen Payment Gateway API. Most API documentation often specify the mandatory and optional body parameters to send in a request and what to expect in response.

• Query Parameters: As the name implies, these types of parameters are embedded into the endpoint URL and it helps filter and properly present the data returned from the server. An example is the Transaction Validation endpoint for Hydrogen’s Instant Pay API.

How do APIs work?

APIs are designed based on certain rules that instruct the application on how to access information and what data to communicate. There are three major parties involved in how APIs communicate and they are the following:

1. User: The individual initiating the communication. (i.e.: a buyer hitting the “Pay Now” button on a website)

2. Client: The application through which the user sends the communication. (i.e.: seller’s website where the buyer clicked the “Pay Now” button)

3. Server: The computer hosting the application to be connected with. (i.e.: connection to “Hydrogen’s Payment Gateway” to redirect the buyer to the payment page)

The very first step is for the engineer to build the server where the application and data will be hosted. Thereafter, the developer will design guides explaining how to connect and access data from the server.

The two phases of communication in the API world are the request and the response. Going back to the buyer example, hitting the “Pay Now” button on the Vendor’s website sends a request while the payment page is a response from the integration which is being rendered on a user-friendly interface.

Integrating with APIs:

Authentication

Authentication forms the most crucial part of most APIs as it helps to verify that the request is genuine, and that the server should proceed with the communication. Authentication is a critical aspect of the Hydrogen API, as it ensures that all requests made to the API are authorized and authenticated before they are processed. 

“Auth tokens are to APIs, just as passwords are to user accounts” - Anonymous 2023

The Hydrogen API requires that all requests be authenticated using an authentication token, which is a unique identifier that is assigned to each user account. The token acts as a digital signature, affirming the identity of the merchant and authorizing the transaction. Without it, the request will not be processed, ensuring an extra layer of security for your users and their financial data.

The developer documentation can help you better understand how to get an authorization token and when to use it for every request.

Sample API request with Hydrogen APIs:

Follow the steps below to make a request with any Hydrogen APIs:

1. Onboard and obtain your Auth tokens for TEST or LIVE integration.

2. Preview the documentation and check the specific API reference for more details.

3. Read the developer docs, focusing on the API reference relevant to your needs.

4. Simulate with any API client of your choice or integrate with your product.

Payment Gateway API

In the following sections, we will proceed to test the payment gateway API using a popular API client known as Postman to simulate initiate payment and confirm payment endpoints.

1. Indicate the method (POST) for this API request

2. Enter the URL endpoint for the API request

 

Navigate to the Headers tab and update the key. In the key field, select “Authorization” and paste your auth token in the next field as a value. Do not alter the authorization token value as that may return errors when making the request.

Navigate to the body tab, select JSON as the format for your request and input the payload. You can refer to the documentation page to copy a sample payload and tweak it for your request. Feel free to include other relevant parameters that might be applicable to your use cases.

"HTML is to websites, just as JSON is to APIs" - Anonymous 2023

1. Hit “Send” to send the payload as a request to the endpoint.

2. The call will return a response similar to this, which includes a URL for the user or customer to complete payment and other important information.

Common API Errors:

API calls might return errors if there are some issues or missing elements of the request. Below are some quick tips to identify common errors and solve them yourself.

• Ensure you are connected to the internet.

• Review the documentation and ensure you are using the right parameters.

• Cross-check that you are not using a live auth token for a test URL or vice-versa.

• Look up the status codes and validate with the API documentation.

By understanding APIs and their integration process, you can leverage these powerful tools to enhance your applications and services. Don’t forget to sign up on Hydrogen today and start interacting with our API products.