Getting started with the Space HTTP API

Maarten Balliauw

Most of the data and operations available in JetBrains Space can be accessed using an HTTP API. The API documentation, as well as the HTTP API playground for your Space organization do a good job in describing the types of interactions that are possible.

In this blog post, we want to look at a few details about working with the Space API more efficiently.

Why would I use the Space API?

Having an HTTP API to access Space makes it easy to share content and data with other applications. We’ve seen our users experiment with creating issues in Space projects, using the API. At JetBrains, we have used the API to import over 1300 user profiles into Space, as well as hundreds of internal blog posts, data about meeting rooms and so on.

Other types of integrations could be receiving build status from a CI server, sharing a message in a chat channel, or even automatically creating a "digest" blog post from issues that have been resolved in the past week.

Playing around with the HTTP API

The documentation describes how to start working with the Space HTTP API, as well as the various OAuth 2.0 flows that are supported to authenticate. But do you really want to go into that when you start exploring what is possible with the Space API?

Using the HTTP API playground (Administration | HTTP API Playground in Space), we can see the operations and data types that are available, without having to worry about authentication and tokens yet – the API playground authorizes calls on our behalf.

We can pick an API call on the left, provide any parameters the API call requires, and then execute the request and look at the response. Use the filter at the top to find a specific API.

As an example, we can set the user interface theme from the API playground, and execute the API from here:

A preview of the HTTP API request is shown on the right-hand side. We can see cURL and JavaScript syntax, and a request that we can copy/paste into any Intellij IDEA-based IDE HTTP client.

Have a look at the request URL in the screenshot above. Did you spot the $fields query parameter? Let’s talk about that one next.

Which fields do we want to see? Shaping results

With most of the API’s in Space, we can shape the results we want to retrieve. If we look at the "Get Me" API for example, to retrieve the current user’s profile information, we can check/uncheck the fields we want to see as part of the result.

Each field that is checked on the left is added into the $fields query parameter on the right. For example, checking the id and about field will set the $fields parameter to $fields=id,about. The API response will only contain those fields:

{
  "id": "3mUkL1WVMESD",
  "about": "Ask me anything."
}

Fields can be primitive values (integers, strings, booleans, …), as well as actual types. For example the user’s name field is of type TD_ProfileName, with a firstName and lastName field of type string.

To fetch the full object tree, we’ll have to specify we want the name field, as well as its inner firstName and lastName. To fetch the full name of the current user, our $fields parameter will become $fields=name(firstName,lastName). The API response that is returned will be similar to the following:

{
  "name": {
    "firstName": "Maarten",
    "lastName": "Clymer"
  }
}

Some API methods return circular references. For example, "Get Profile by Username" returns a user profile, where we can include team memberships. Those, in turn, can include the team information which again can contain user profiles with team memberships, and so on.

We recommend not fetching full hierarchies all the time, as this will increase response size and might make your calling code more complex. Of course, if a more elaborate hierarchy is needed for a certain scenario, you can retrieve it from the API.

Being able to retrieve just the information your integration requires helps in reducing payload size, and ultimately in a better performing integration overall.

HTTP API metadata

There’s one special HTTP API endpoint in the Space API: "Get HTTP API Model". This endpoint returns metadata for the Space API:

• Dto – a collection of all of the types the API works with;
• Enums – a collection of all of the enums the API works with;
• Endpoints – a collection describing all possible API calls, their parameters and so on.

Here are some example enums returned from the API:

All of this information can be used to generate a strongly typed API client for Space. It contains information about the type hierarchy and inheritance, nullability of fields, and more.

Conclusion

The Space API can be used to integrate your own applications with various areas of Space, whether it’s posting a message to a chat, importing issues from GitHub or JIRA, there are already APIs available for doing these and more.

Remember, you can customize the shape of the data returned from the API, by making use of the $fields query parameter. This reduces the response payload size, and makes your integration faster and more efficient.

Lastly, have a look at the "Get HTTP API Model" endpoint to retrieve metadata about all of the Space API’s.

Give JetBrains Space EAP a try, and let us know about what you want to build with the API. We’re curious to see what’s brewing.

Subscribe to Space Blog updates

Subscribe form

By submitting this form, I agree to the JetBrains Privacy Policy Notification icon

By submitting this form, I agree that JetBrains s.r.o. ("JetBrains") may use my name, email address, and location data to send me newsletters, including commercial communications, and to process my personal data for this purpose. I agree that JetBrains may process said data using third-party services for this purpose in accordance with the JetBrains Privacy Policy. I understand that I can revoke this consent at any time in my profile. In addition, an unsubscribe link is included in each email.

Submit

Thanks, we've got you!