Introduction to APIs

1 What is an API?
2 How to use our API
3 What is GraphQL?
4 How to use our API
- 4.1 Examples
  - 4.1.1 Curl (searchOpportunities)
  - 4.1.2 Fetch (searchOpportunities)
  - 4.1.3 NodeJs with axios (getConnections)

What is an API?

An API, which stands for "Application Programming Interface," is like a messenger or translator that allows two different software programs to communicate with each other.

In the world of software, an API is a set of rules and protocols that allows different applications to "talk" to each other. When you use an app on your phone or computer, it might be using an API to connect to a server or database to get the information it needs to function properly.

For example, if you use a weather app to check the forecast, the app might use an API to connect to a weather service that provides up-to-date weather information. The app sends a request to the API for the current weather data, and the API responds with the data the app needs.

In the case of VolunteerMatch, you can use our APIs to get information from or to change data in our application. One example would be using our API to get a list of opportunities based on some specifications (location, cause area, etc) to display on your website. Another example would be using the API to add or remove an opportunity in our database.

So, an API basically acts as an intermediary between two different software applications, allowing them to communicate and exchange information in a standardized way. This makes it easier for developers to build new applications and services that can work with other existing systems.

How to use our API

Using our API typically involves the following steps:

Register for an API key: Our API requires you to get an API key from us, which is a unique identifier that is used to authenticate API requests.
1. You can read more about our plans and pricing here
2. Start the registration process here
Read the API documentation: API documentation provides information about the API's endpoints, request parameters, and response data. It's important to understand this information before making API requests.
Make API requests (see request examples below): API requests are usually made using HTTP methods such as GET, POST, PUT, and DELETE. The request is sent to a specific endpoint, along with any required parameters and the API key. Here are some requests you can make:
1. searchOpportunities - allows you to search our expansive database of volunteer opportunities. The data will be returned by the API in JSON format
2. createConnections - allows you to create connections between users and VolunteerMatch opportunities
Parse the API response: The API will return a response, which will most likely be in JSON format like this example below. The response must be parsed in order to extract the data you need.
Use the API data: Once you have parsed the API response, you can use the data in your own software application as needed.

What is GraphQL?

GraphQL is a Query Language that helps Application Programming Interfaces (APIs) fetch only that data which is requested by the client, and nothing else. This enormously reduces the redundant data at the API endpoint and making the requests blazing fast and developer friendly. Because GraphQL operates over HTTP, you can use any language, client library, or tool to fetch GraphQL data so long as you format the HTTP request properly.

GraphQL has a number of benefits over traditional REST APIs, including:

More efficient and flexible: With GraphQL, you can request exactly the data you need, and nothing more. This means that you don't waste bandwidth and resources retrieving data that you don't need.
Strongly typed: GraphQL has a schema that describes the types of data that are available, making it easier to catch errors and ensuring that clients receive the right data.
Works well with modern front-end frameworks: GraphQL is designed to work well with modern front-end frameworks like React, Angular, and Vue, making it easier to build fast, responsive, and scalable applications.

Overall, GraphQL is a more efficient and flexible way to request data from APIs, and has become a popular choice for building modern, scalable applications.

Helpful links for using GraphQL with our API:

https://graphql.org/learn/
https://graphql.org/code/
VolunteerMatch GraphQL Schema
Test out your queries here (there is also a documentation explorer you can use)
- Example query:

How to use our API

You may need an engineer to help you if you don’t have a basic understanding of how to use APIs. You will need to have an understanding of code and how APIs work in order to use it.

Helpful tools for testing our API:

https://www.gatsbyjs.com/docs/how-to/querying-data/running-queries-with-graphiql/
(can also generate code like the examples below)

Here is how to get started with a few different ways of calling our API to get some data:

Examples

Curl (searchOpportunities)

curl --location --request POST 'https://graphql.stage.volunteermatch.org/graphql/' \
--header 'x-api-key: API-KEY-HERE' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"query {\n  searchOpportunities(input:{\n\t\tlocation:\"75234\"\n  }){\n    currentPage\n    resultsSize\n    opportunities {\n      id\n      title\n      location{city, postalCode, region}\n      datePosted\n    }\n  }\n}","variables":{}}'

Response:

{
  "data" : {
    "searchOpportunities" : {
      "currentPage" : 1,
      "resultsSize" : 5,
      "opportunities" : [ {
        "id" : 947176,
        "title" : "Become a Mentor: Mercy Street",
        "location" : {
          "city" : "Dallas",
          "postalCode" : "75212",
          "region" : "TX"
        },
        "datePosted" : "2022-01-12"
      }, {
        "id" : 942711,
        "title" : "test gov't dallas",
        "location" : {
          "city" : "Dallas",
          "postalCode" : "75229",
          "region" : "TX"
        },
        "datePosted" : "2022-01-12"
      }, {
        "id" : 947063,
        "title" : "Become a Mentor: Big Brothers Big Sisters Lone Star",
        "location" : {
          "city" : "Irving",
          "postalCode" : "75062",
          "region" : "TX"
        },
        "datePosted" : "2022-01-12"
      }, {
        "id" : 947079,
        "title" : "Become a Mentor: All Things Made New",
        "location" : {
          "city" : "Irving",
          "postalCode" : "75060",
          "region" : "TX"
        },
        "datePosted" : "2022-01-12"
      }, {
        "id" : 942816,
        "title" : "map loc testing",
        "location" : {
          "city" : "around texas",
          "postalCode" : "75261",
          "region" : "TX"
        },
        "datePosted" : "2022-01-12"
      } ]
    }
  }
}

Fetch (searchOpportunities)

You can make a GraphQL HTTP request in literally any programming language. So let’s convert that curl request into some JavaScript code with fetch, the new standard for getting HTTP results with promises. This will work in modern browsers with no libraries, but will require a polyfill in Node and some browsers. Here is an example (response will look similar to the curl response above):

var myHeaders = new Headers();
myHeaders.append("x-api-key", "API-KEY-HERE");
myHeaders.append("Content-Type", "application/json");

var graphql = JSON.stringify({
  query: `query {
  searchOpportunities(input:{
    location: "san francisco"
    categories:[childrenAndYouth, community]
    pageNumber:1
    sortCriteria: update
  }){
    resultsSize,
    opportunities{
      id,
      title 
      categories
      specialFlag
  }}
  }`
})
var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: graphql,
  redirect: 'follow'
};

fetch("https://graphql.stage.volunteermatch.org/graphql/", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

NodeJs with axios (getConnections)

Results: