Frequently Asked Questions

APIs & Technical Architecture

What is an API and how does it work?

An API (Application Programming Interface) is a set of rules and protocols that allows different software components to communicate with each other. APIs define how requests and responses are formatted and exchanged, enabling applications to interact seamlessly. For example, when you search for a product on Amazon, the app communicates with Amazon's servers via APIs to retrieve and display product data. APIs can be used by both frontend and backend systems, and are essential for modern software integration. Learn more.

What types of APIs does Hygraph support?

Hygraph provides a powerful GraphQL API for efficient content querying and management. It also supports RESTful integrations and can be used in conjunction with other API types such as WebSocket APIs and Web APIs, depending on your application's needs. For more details, see the Hygraph API Reference.

How do APIs facilitate communication in applications?

APIs enable communication by allowing a client (such as a mobile app or web frontend) to send a request to a server, which processes the request and sends back a response. This mechanism is essential for functionalities like searching for products, user authentication, and data retrieval. APIs act as gateways, ensuring that internal changes in one system do not affect others as long as the API contract remains unchanged. Read more.

How does Hygraph use APIs in its architecture?

Hygraph uses APIs, particularly GraphQL, to connect data sources and deliver content to the frontend. This API-first approach allows developers to adapt to new requirements without having to rewire the entire architecture, making it easier to scale and integrate with other systems. Learn more about Hygraph's API usage.

Can you provide an example of how APIs work in a real application?

Consider a simple authentication service that exposes two APIs: register and login. The backend server interacts with Hygraph CMS to perform CRUD operations and sends email confirmations through an email service. The client applications (web or mobile) communicate with the backend server, which in turn communicates with Hygraph and other services via APIs. See the full example.

Features & Capabilities

What features does Hygraph offer?

Hygraph offers a GraphQL-native architecture, content federation, scalability, and a wide range of integrations. Key features include a powerful GraphQL API, support for content federation, robust security and compliance, and integrations with platforms like Netlify, Vercel, Shopify, AWS S3, Cloudinary, and more. For a full list, visit the Hygraph Features page.

What integrations are available with Hygraph?

Hygraph integrates with a variety of platforms, including Netlify, Vercel, BigCommerce, commercetools, Shopify, Lokalise, Crowdin, EasyTranslate, Smartling, Aprimo, AWS S3, Bynder, Cloudinary, Mux, Scaleflex Filerobot, Ninetailed, AltText.ai, Adminix, and Plasmic. For a complete list, see the Hygraph Integrations page.

Does Hygraph provide technical documentation?

Yes, Hygraph offers comprehensive technical documentation covering all aspects of building and deploying projects, including API references, integration guides, and onboarding resources. Access the documentation at Hygraph Documentation.

How does Hygraph ensure content delivery performance?

Hygraph is optimized for rapid content delivery, which improves user experience, engagement, and search engine rankings. Fast content distribution reduces bounce rates and increases conversions. For more details, visit the Headless CMS Checklist.

Security & Compliance

What security and compliance certifications does Hygraph have?

Hygraph is SOC 2 Type 2 compliant, ISO 27001 certified, and GDPR compliant. These certifications ensure high levels of data protection and security for users. For more information, visit the Hygraph Security Features page.

How does Hygraph protect sensitive data?

Hygraph provides enterprise-grade security features, including SSO integrations, audit logs, encryption at rest and in transit, and sandbox environments. These measures help protect sensitive data and meet regulatory standards. More details are available on the Hygraph Security Features page.

Pricing & Plans

What is Hygraph's pricing model?

Hygraph offers a free forever Hobby plan, a Growth plan starting at $199/month, and custom Enterprise plans. For full details, visit the Hygraph Pricing page.

Use Cases & Benefits

Who can benefit from using Hygraph?

Hygraph is ideal for developers, IT decision-makers, content creators, project/program managers, agencies, solution partners, and technology partners. It is especially beneficial for modern software companies, enterprises looking to modernize their tech stack, and brands aiming to scale across geographies or improve development velocity. See case studies.

What problems does Hygraph solve?

Hygraph addresses operational pains (like reliance on developers for content updates, outdated tech stacks, and clunky content creation), financial pains (high operational costs, slow speed-to-market, expensive maintenance, and scalability challenges), and technical pains (boilerplate code, overwhelming queries, evolving schemas, cache problems, and OpenID integration challenges). Learn more.

What business impact can customers expect from using Hygraph?

Customers can expect significant time savings, faster speed-to-market, improved customer experience, and enhanced operational efficiency. For example, Komax achieved 3X faster time to market, and Autoweb saw a 20% increase in website monetization. See more success stories.

What industries are represented in Hygraph's case studies?

Hygraph's case studies span industries such as food and beverage, consumer electronics, automotive, healthcare, travel and hospitality, media and publishing, eCommerce, SaaS, marketplace, education technology, and wellness and fitness. Explore case studies.

Can you share specific customer success stories with Hygraph?

Yes. Komax achieved a 3X faster time to market, Autoweb saw a 20% increase in website monetization, Samsung improved customer engagement with a scalable platform, and Dr. Oetker enhanced their digital experience using MACH architecture. Read more customer stories.

Getting Started & Support

How easy is it to get started with Hygraph?

Hygraph is designed for ease of use, even for non-technical users. You can sign up for a free-forever account and access resources like documentation, video tutorials, and onboarding guides. For example, Top Villas launched a new project in just 2 months from the initial touchpoint. Get started here.

What support and training does Hygraph offer?

Hygraph provides 24/7 support via chat, email, and phone. Enterprise customers receive dedicated onboarding and expert guidance. All users have access to detailed documentation, video tutorials, and a community Slack channel. Training resources include onboarding sessions, webinars, and Customer Success Managers for enterprise clients. Contact support.

What feedback have customers given about Hygraph's ease of use?

Customers have praised Hygraph for its intuitive and user-friendly interface, noting that it is 'super easy to set up and use' and accessible for both technical and non-technical users. Read more feedback.

Company & Vision

What is Hygraph's vision and mission?

Hygraph's vision is to unify data and enable content federation, empowering businesses to create impactful digital experiences. Its mission is to remove traditional content management pain points through a GraphQL-native architecture, helping businesses modernize their tech stacks and deliver exceptional digital experiences at scale. Learn more about Hygraph.

Customer Proof

Who are some of Hygraph's customers?

Hygraph is trusted by leading brands such as Sennheiser, HolidayCheck, Ancestry, Samsung, Dr. Oetker, Epic Games, Bandai Namco, Gamescom, Leo Vegas, and Clayton Homes. See more customer stories.

Velocity at Scale: Join the Launch of Hygraph’s Latest AI Innovations

How do APIs Work? A Beginner's Guide

Let's take a look at what are APIs, how they work and, what kind of different APIs exist. You will learn also its benefits and the advantages of each.
Hygraph Team

Written by Hygraph 

Sep 12, 2022
how do apis work

#What is an API?

API stands for Application Programming Interface, when any two software components need to communicate with each other they can do so with the help of an API. APIs have their own set of predefined rules, protocols, and definitions based on which the communication takes place. All applications that we use in our day-to-day lives are in a way powered by APIs, they kind of form the backbone of communication.

For instance, when you search for a product on Amazon, the Amazon app on your phone communicates with the Amazon servers that will send back the list of items to show you. The app on your phone (client) will send a request to the Amazon backend servers, which will handle the request, gather appropriate data from a cache layer or a database server, prepare a response, and send it back to the client. For any API, the request and response formats will be defined earlier and documented for future reference. For instance, in the case of a “Search Product API”, the request needs to contain the keywords to search for, the identity of the user who is sending the request, and the response format could be an array of objects that will have certain key-value pairs based on which the client will display the product list.

It’s not only mobile apps or web-facing frontend apps that can be API clients for consuming data, even backend servers can be clients of other backend APIs. For example, an application’s backend API for registering a user can insert the user record in the database and then communicate to an email service via an API call for sending a confirmation email to the user. The application that is requesting the data is the client and the application that sends the response is the server.

#How do APIs work

All APIs have their own set of protocols and definitions, so each and every API type will have a different type of operating mechanism. There are different types of APIs like REST APIs, GraphQL, Websocket APIs, SOAP, RPC APIs, and more. We will discuss the most important ones currently in Software Engineering.

REST APIs

REST stands for REpresentational State Transfer. Rest APIs are very popular and for a long time, they were the de facto standard for developing backend APIs. They are used by everyone from enterprises to small-scale companies in their software projects.

How REST APIs work

The above image depicts the most common way developers implement REST APIs. The client can send requests with HTTP methods like:

  • GET - retrieve data
  • POST - create data
  • PUT - replace data
  • PATCH - partially modify data
  • DELETE - remove data

Note that, depending on the API, some of these methods may not be available. Finally, the data to be exchanged can be in JSON or XML format (JSON is a popular default choice).

How a REST API works:

  • A REST request is made up of the endpoint, HTTP method, Header, and Body.
  • When a client requires a resource, it contacts the server via an API call. The endpoint URL and required parameters/headers/body of the request are agreed upon earlier.
  • The server confirms if the client is authorized to make that API request and if so it proceeds ahead.
  • The server processes the request, it can reach out to other services, databases, and caches to gather the required information, but the client will not be aware of how the server is fulfilling the request.
  • The server sends a response to the client, which includes if the request was successful or not and the information requested.

For example, To get the list of products the client can hit GET /products API on the server with the authentication token of the user in the headers of the request and if the token is valid the server process the request and return an array of objects with all product information, there will be a common agreement between the client and server decided beforehand, this agreement is known as an API Contract.

If we were to send a request to themoviedb.org API to fetch the details of a particular movie, in Python, it would look like this:

import requests
api_url = "https://api.themoviedb.org/3/movie/"
movie_id = "400617"
response = requests.get(api_url + movie_id + "?api_key=" + API_KEY) # API_KEY defined behind the scenes
print(response.json())

The response would look like the following:

{
"adult": false,
"backdrop_path": "/vpRMzPqHC03I7hPPET4Av2OT8dI.jpg",
"belongs_to_collection": null,
"budget": 35000000,
"genres": [
{
"id": 18,
"name": "Drama"
},
{
"id": 10749,
"name": "Romance"
}
],
"homepage": "http://focusfeatures.com/phantom-thread",
"id": 400617,
"imdb_id": "tt5776858",
"original_language": "en",
"original_title": "Phantom Thread",
"overview": "In 1950s London, renowned British dressmaker Reynolds Woodcock comes across Alma, a young, strong-willed woman, who soon becomes ever present in his life as his muse and lover.",
"popularity": 16.068,
"poster_path": "/hgoWjp9Sh0MI97eAMZCnIoVfgvq.jpg",
"production_companies": [
{
"id": 178,
"logo_path": null,
"name": "Ghoulardi Film Company",
"origin_country": "US"
},
{
"id": 10146,
"logo_path": "/xnFIOeq5cKw09kCWqV7foWDe4AA.png",
"name": "Focus Features",
"origin_country": "US"
},
{
"id": 10338,
"logo_path": "/el2ap6lvjcEDdbyJoB3oKiYgXu9.png",
"name": "Perfect World Pictures",
"origin_country": "CN"
},
{
"id": 13184,
"logo_path": "/pfUB1a62jSMIqp4Xmaq6z2cgW0B.png",
"name": "Annapurna Pictures",
"origin_country": "US"
}
],
"production_countries": [
{
"iso_3166_1": "US",
"name": "United States of America"
},
{
"iso_3166_1": "GB",
"name": "United Kingdom"
}
],
"release_date": "2017-12-25",
"revenue": 47756590,
"runtime": 130,
"spoken_languages": [
{
"english_name": "English",
"iso_639_1": "en",
"name": "English"
},
{
"english_name": "French",
"iso_639_1": "fr",
"name": "Français"
}
],
"status": "Released",
"tagline": "",
"title": "Phantom Thread",
"video": false,
"vote_average": 7.297,
"vote_count": 2938
}

The response structure is the way it is defined in the API and it will always be the same. If you would like to request additional information you would have to make a request to another endpoint. A Rest API is stateless, meaning that the server will not maintain any client-related information (state), and the client will have to identify itself on every request.

GraphQL API

As per GraphQL’s official website, “GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.” Those who are new to GraphQL please refer to this article for an in-depth introduction to GraphQL. In recent years, GraphQL is gaining traction quite aggressively and many enterprise companies are moving towards using GraphQL to support their use cases.

REST APIs were quite powerful and the default choice for API development for more than a decade, but with time some disadvantages started making a difference. Some of the disadvantages are

  • All resources have a different endpoint
  • Overfetching, Underfetching, N+1 Request problem
  • High coupling between the client requirements and the backend APIs

GraphQL has only one endpoint, and the data you require is defined in the request itself. If you recall the example from the section above on REST APIs with themoviedb.org, GraphQL would help remove the unnecessary information and add something additional to the response with just one call only.

For example, if we were to require only a title, overview, or cover image that response would deliver too much information. In addition, if we were to add the director and performers for main roles, we would have to fetch the data from another endpoint. In GraphQL, this could look like this:

query getMovie($id: String!) {
movies(where: { id: $id }) {
title
overview
coverImage {
url
}
director {
name
}
performers {
name
}
}
}

GraphQL is a solution to all these problems and you can read more on GraphQL vs REST.

Hygraph is a GraphQL-native Federated Content Platform that provides developers with a powerful and extensible GraphQL API. We empower developers with a powerful query & mutation API that is ready to use within seconds. All you need to do is sign up with a free plan and configure your schema to get started.

WebSocket APIs

Rest APIs are quite popular when the use case is uni-directional communication. The client establishes a TCP connection, requests some data from the server, the server authenticates the client, processes the request, and sends back a response, then the TCP connection is closed. Next time, the client needs something, a fresh TCP connection will be established and the same process will be repeated. This approach works well when you need to show a list of products, search through them or show a product detail page, but it would be very terrible for user experience if used to build chat systems, where the expectations are of real-time communication.

Introducing WebSockets, their primary use case is to support superfast bi-directional communication, it is stateful in nature, works on a full-duplex model wherein both the client and server can send any number of requests back and forth and there will be a single TCP connection established at the very start. The everyday chat applications that we use like Slack, Whatsapp, and others rely heavily on WebSockets as their backbone.

Web APIs

When working with an application that will have access to a web browser, for instance, any frontend facing HTML, CSS, JavaScript / React / Vue / Angular, etc applications. You also have the superpower to use the large set of Web APIs exposed by the web browser.

When working with frontend web applications, developers often use HTML DOM API or use libraries that in turn use the HTML DOM API. It allows you to manipulate the HTML Document Object Model that is rendered by the browser on your screen. The DOM tree includes the elements such as <body> , <div> , and more. This API comes in handy when you want to dynamically make changes to the elements during runtime.

This HTML file has a script which has a function setBodyAttr, it is using document object to manipulate the background color of the body element on runtime in the browser.

#Example

Let us try to understand the working of APIs in general via a high-level example. Here is the architecture of a very simple Auth Service that exposes two APIs - register, and login and is capable of sending emails.

Simple Authentication Service

The components of this backend service include:

  • Some client applications
  • Backend web server
  • Hygraph headless content platform
  • An email service.

The client applications can be mobile or web applications, they will know the backend server’s URL and the backend server will be the only point of communication for them. Also, they will know the API endpoint and the request parameters for the login and register APIs exposed by the backend server. The client apps prepare the appropriate request payload and will make an API call to the Backend Server.

The backend server can either be a REST API server or a GraphQL server, it will have the business logic of the Register and Login API, validate the inputs received from the client apps, and interact with our Hygraph CMS to perform CRUD operations on the database. For example, for Register API, it will first need to check if a user with the same email already exists, for login API, it will need to validate the username and password, hence the backend server will need to communicate to Hygraph. While interacting with the Hygraph CMS, the backend server will act as a client and make API calls with GraphQL queries and mutations toHygraph which will in turn perform operations on the database.

After the above steps, the backend server will send email confirmations for which it will prepare the proper request payload as per the email service’s API contract and trigger an API call to the email service, the email service’s responsibility will be to send the confirmation emails to the users, and finally, the backend server will process and send final responses to the client as agreed in the API contract which must be defined at the very start.

Please note that this is a very simple auth service to understand “API calls” better, a real-life auth service will be much more complex and can have more layers, OAuth flows, job queues, and more.

#Benefits Of Using API

Integration & Developer Productivity

With APIs, you can integrate new applications with existing software systems. This increases development speed because you don’t have to write all of the functionality from scratch and you can reuse existing functionalities. Developers can focus more on the crux of the product instead of the other services which are generic and can be easily outsourced.

Costing

Many times, the cost of creating and maintaining a new service and its infrastructure from scratch at scale exceeds the cost of outsourcing it to a reliable giant who can do it right. Here the API integrations come in handy for cutting costs.

Maintenance

APIs act as gateways between two systems. When required the systems change their code internally ensuring they do not change the defined API contract, this way any future code changes from one party do not affect the others.

Improved value proposition

Applications can make themselves more appealing to customers by integrating APIs made available by well-known companies like Google, Amazon, etc.

#Conclusion

Overall, understanding the core concept of different APIs, their use case, protocols, and their operating mechanism is a must as they are the standard way of communication between applications and offer many benefits. Starting from base, we recommend getting your hands dirty on GraphQL and Rest APIs at the very least and then one can explore WebSockets.

Blog Author

Hygraph Team

Hygraph Team

Share with others

Sign up for our newsletter!

Be the first to know about releases and industry news and insights.