Intro to the GForgeNext API

GForgeNext is the newest incarnation of our long-lived project collaboration tool.  It ties together all of the most important features that teams need to deliver big things – like task tracking, team chat and integrated source control.   And in the next several months, we’ll add a lot more.

Next employs a Single Page Application (SPA) front end, and relies on our public REST API for all of its functionality.  Everyone can now build great tools and integration points with GForge using the same REST API that we do.

On that topic, then, let’s explore the API and build an example or two.

REST Basics

There are plenty of good, detailed tutorials about REST.  Here are the basics you need to get started with ours:

  • REST deals in resources.  In our case, things like users and projects.
  • REST uses the HTTP verbs you already know to get things done.  GET, POST, PUT and DELETE are the most common.
  • REST also uses the same HTTP response codes that web pages use.  404?  That record doesn’t exist.  400?  You submitted something invalid.  500?  You broke it.
  • REST uses the normal query string and request body that HTML pages use.
  • Data is typically exchanged (submitted and returned) in JSON format, which is easy to handle on most platforms.
  • Our REST API also accepts regular FORM POST format, so it can be called even from static HTML pages or libcurl.
  • All of the resources, methods and parameters for the API are documented in our API Docs.

Logging In

GForge has very deep and flexible access controls, and the data you receive from the API will usually depend on the user requesting it.  You can submit a separate user ID and password with each request, or get a session ID (from the /usersession endpoint).

Using curl:

[code language=”bash”]
curl -X POST https://USERNAME:PASSWORD@next.gforge.com/api/usersession
[/code]

Results in:

[code language=”javascript”]
<pre>{
"SessionHash":"e3403h9ldbssr2…o781jne2"
}
[/code]

The POST verb is used to create data on the server – in this case, a new session ID is created if the user and password match up.  You can then use the session ID in place of the password for further requests.  In a browser, the session ID will also be set in a cookie just like visiting the login page on a web site.

To “log out” and remove this session:

[code language=”bash”]
curl -X DELETE https://USERNAME:SESSION@next.gforge.com/api/usersession/SESSION
[/code]

Result:

[code language=”javascript”]
{"result":"success"}
[/code]

Note that you have to include the session ID for both the authentication and to specify which session to delete.

Get Some Data

Now that we have an authenticated user, we can use it to get data from the API.  How about the user profile for a friend?

Request:

[code language=”bash”]

curl https://myuser:e3403…jne2@next.gforge.com/api/user/my_friend

[/code]

Result:

[code language=”javascript”]

{"id":99999,"unixName":"my_friend","password":null,"firstName":"My","lastName":"Friend",
"email":"my_friend@email.tld","status":1,"externalId":null,"isGroup":"N",
"ccode":"US","language":"en ",
"img_url":"/images/custom_avatars/99999.jpg",
"details_url":"/api/user/my_friend/details","api_url":"/api/user/my_friend"}

[/code]

What’s Next?

Read the API docs, and see what you can get under the /api/user and /api/project endpoints.  There are a whole bunch of sub-entities within each one.  Then maybe move on to /api/tracker or even /api/trackeritem to see tasks.

For the especially brave, try /api/poll…

Got questions?  Comments?  Bugs? Leave a comment, or find me on Twitter @mtutty.