Building a Marvel Integration in Javascript, Using Our GraphQL API
By Maxime De Greve, Designer & Developer at Marvel
If you’ve been following us a little these last few months, you probably noticed we’ve launched a series of small applications built on top of our Platform API.
Including:
- BotBot: Automate Marvel tasks in Slack by using slash commands, such as creating and adding people to projects or pulling up a searchable list.
- Marvel for Keynote: A Mac app which allows you to upload Keynote documents to Marvel
- Dashboard: A microsite that displays the latest designs uploaded to Marvel by members of your team
- Userflows: A tool which quickly converts prototypes into user journey diagrams.
These little applications are only the tip of the iceberg of what’s possible with the Marvel API.
We built these not only to enhance your Marvel experience but also to showcase how to use our Platform API, it’s something we launched earlier in the year to allow you to access Marvel’s core functionality and build your own tools, apps and integrations. Therefore BotBot, Marvel for Keynote and Dashboard are all open source and can be found on our GitHub account.
Alright let’s build a simple, “The owner of this Marvel account is: [your name]” web application.
What do you need?
- Pick a coding language, we’ll use Javascript in this.
- Visit https://marvelapp.com/oauth/devtoken and save the token. We’ll need this to connect to your Marvel account later on.
- Read our documentation, especially if you’re not clear on how specific things work after this tutorial. https://marvelapp.com/developers/documentation/
If you quickly scan through our documentation you’ll notice our API uses something called GraphQL, instead of a classic REST API. At first, this fancy word sounded scary to me but it’s actually more flexible and easy to understand than REST API’s, which can often give you back too much data that you have to scan through.
For example, when I need the name and email of a user:
A classic REST API returns:
- name
- address
- age
- city
A GraphQL API returns only what you need:
- name
- address (I don’t need this)
- age (I don’t need this)
- city (I don’t need this)
Therefore there is less data for your integration to scan through, which is faster for the Marvel API, faster for your integration and easier to understand by you when going through this data.
Starting to write your integration
Alright, let’s write something in Javascript to understand this better.
First let’s create a hello.html file and add this to it:
<!DOCTYPE html>
<html>
<head>
<title>Hello</title>
<script>
// Here we'll add our Javascript
</script>
</head>
<body>
<h1 id="target"></h1>
</body>
</html>Now, let’s fetch your name from the Marvel API by adding some basic Javascript inside the <script> tag:
<!DOCTYPE html>
<html>
<head>
<title>Hello</title>
<script>
// Here we'll add our Javascript
var apiUrl = "https://api.marvelapp.com/graphql/";
var token = "YOUR TOKEN FOUND IN https://marvelapp.com/oauth/devtoken";
var query = "query { user { username email } }"; var xhr = new XMLHttpRequest();
xhr.open("POST", apiUrl);
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Authorization", "Bearer " + token);
xhr.onreadystatechange = function() {
if (this.readyState == 4 && this.status == 200) {
var responseJSON = JSON.parse(this.responseText); // So you can see in your browser console what got returned
console.log(responseJSON); // Let's set the text of the H1 tag to your name
document.getElementById("target").innerHTML =
"The owner of this Marvel account is: " + responseJSON.data.user.username;
}
};
xhr.send(JSON.stringify({ query: query }));
</script>
</head>
<body>
<h1 id="target"></h1>
</body>
</html>
Woah that’s a lot to digest in one go…
GraphQL queries
The first two lines are might be straightforward, but the third line is probably where things feel a bit new. When talking about the difference between REST API’s and a GraphQL API, I explained that you only query what you need, to avoid fetching the data you don’t need. To do this you need to write a GraphQL query.
To make it easier for everyone to get started with this, we’ve added a few common query examples to our documentation. Check them out here.
Now you’re more than likely wondering what other properties are available on the user, other than simply their username and email. For that you can use our reference documentation which can be found here.
Or you could just use our GraphQL playground over here.
This has auto completion and a docs sidebar, perfect for when you want to write and test your queries before using them in code.
Wrapping up
When you open your html file now you should be able to see who the owner is of your Marvel account. (Note: you might have to turn your cross origin setting off in your browser)
When you view the console of your browser you will also see what information the API returned after querying it with GraphQL query.
Questions
If whilst using our API and after reading our documentation, there are some questions remain unanswered, join our Slack Community.
Thanks for reading! This post was originally published on blog.marvelapp.com. You can read more about what we do here and who we are here.
