You may have heard of GraphQL, a young and fast-growing API architecture style that is becoming increasingly popular among developers. Although REST remains dominant and some developers may be hesitant to use an unfamiliar architecture, GraphQL has seen wide adoption in data-heavy industries, such as e-commerce.
But what exactly is GraphQL? Simply put, it's a query language for APIs, designed to give users more flexibility and efficiency when retrieving data. In this article, we’ll explore the benefits of using GraphQL over REST for weather APIs and provide examples of how to make requests to Meteum API
GraphQL Vs. REST
According to Postman's State of the API 2022 report, GraphQL is one of the top four architectural styles of API, with 28% of developers using it. Compare that to 24% in 2021, or to 22.5% in 2020: GraphQL is picking up pace year by year. We’re confident this number will continue to grow, and there are numerous reasons for it.
Architectural API style. Source: Postman
To illustrate them, here’s an example using mock parameters. We're requesting forecasting data for New York City for five days. Let’s say we’re specifically interested in temperature and humidity and want to see both the current and the daily forecast. With REST, we’d need to specify these parameters as query parameters, which would result in an unwieldy URL:
GET /weather?city=New+York&date=YYYY-MM-DD&temperature_unit=FAHRENHEIT&humidity=true&forecast_days=5
The REST API response would be a flat JSON object that dumps all of the requested data in a single level and also includes info that we didn’t explicitly request. Imagine if we were requesting data for several locations and a range of several months — the horror!
In contrast, with GraphQL, we can request all of the necessary data with a single query, and we can even group the data into separate fields for the current weather conditions and a daily forecast:
query {
weather(city: "New York", date: "YYYY-MM-DD", forecastDays: 5) {
now {
temperature(unit: FAHRENHEIT)
humidity
}
daily {
// …
}
}
}
The response will be a neat and tidy hierarchical JSON object with nested fields that correspond to the requested data:
{
"data": {
"weather": {
"current": {
"temperature": {
"value": 40,
"unit": "FAHRENHEIT"
},
"humidity": 70
},
"daily": {
// ...
}
}
}
}
GraphQL makes it much easier to request and manage complex data structures. The automatic documentation and strongly-typed system of GraphQL also simplify work with the various data types and units of measurement commonly found in weather APIs like ours.
There are many more differences under the hood. Learn about the key advantages that GraphQL offers with a direct comparison against REST:
| REST | GraphQL |
|
Overfetching and underfetching of data due to rigid endpoints that return fixed data structures |
Ability to retrieve only the necessary data in a single request |
|
Requires multiple requests to fetch related resources; slow performance |
Ability to retrieve related resources in a single request; fast performance |
|
Limited versioning and backward compatibility, new versions may break functionality |
Strong typing and introspection capabilities, which allow for better documentation and easier evolution |
|
Ad hoc nature of REST APIs makes it challenging to optimize queries for specific use cases |
Ability to optimize queries based on specific use cases with its declarative nature |
|
Inflexibility in the face of changing requirements, leading to the creation of new endpoints and versioning |
Flexibility and adaptability due to its schema-based approach and the ability to add new fields without breaking existing queries |
|
Difficulty in testing due to the lack of a schema and reliance on documentation for understanding endpoint behavior |
Ability to leverage schema for generating documentation, validating queries, and providing type-checking; easier testing |
Getting Started With Meteum API
To get access to the Meteum API, log in to the Meteum developer portal using your work account (Google, Slack), or create a new Meteum account with your work email.
After logging in to the portal, you can start your free trial or choose the API access plan that best suits your needs. You'll find a new key in your account as soon as your plan is active. The key is usable a few minutes after creation.
Authorization
You can use your key to access the API. For it to work, you need each API request to pass this key as an HTTP request header. The header is called X-Meteum-API-Key.
To check if the key works via the terminal command line, use this sample query:
curl 'https://api.meteum.ai/graphql/query' -H 'X-Meteum-API-Key: <Key>' -H 'Content-Type: application/json' --data-binary '{"query":"{ weatherByPoint(request: { lat: 52.37125, lon: 4.89388 }) { now { temperature }}}"}
Sending your first request
Sending requests to Meteum API is simple: each request is enclosed in curly braces and includes request parameters. For example, to get the current temperature at a specific location, you would call the weatherByPoint method with the request parameter specifying the latitude and longitude of the location. You can then specify which weather parameters you need, such as the temperature, and execute the request:
{
weatherByPoint(request: { lat: 52.37125, lon: 4.89388 }) {
now {
temperature
}
}
}
Meteum API is equipped with a sandbox environment where you can create and execute requests using autocomplete features and tips that describe the GraphQL API schema in detail. The sandbox also includes ready-made JavaScript and Python code snippets for your queries.
Please refer to our documentation for more examples and a deeper look into Meteum API features, GraphQL syntax, and initial setup. You can find more examples and run test queries in Meteum’s Postman workspace.
As we’ve established, GraphQL is a powerful and easy-to-learn way to retrieve data from APIs. We chose GraphQL to create a delightfully fast, functional, efficient, and elegant API platform. Retrieve exactly the data you need for any location on Earth — be it historical weather records, live observations, short-term forecasts, or long-term forecasts.
Experience the full suite of features by getting a free key at meteum.ai. The trial gives you access to all API features normally available to Professional subscription users, including the Meteum Rain API for deep precipitation data.
If you need something specific that we don’t yet offer out of the box, reach out to us, and we'll do our best to fulfill your requirements.