Getting started with the PoolParty API

This technical note is here to get you started on making your own semantic software using the PoolParty API.

PoolParty is a software system for creating and managing information taxonomies, controlled vocabularies and ontologies. Content stored in PoolParty can be managed and displayed through the PoolParty web application using a variety of interfaces to suit different purposes. PoolParty also provides the capability, through SPARQL endpoints or via a RESTful Application Programming Interface (API), for external software applications to directly query the PoolParty repository.

This article describes how to create simple software programs that will retrieve data from PoolParty using its API. The official PoolParty developer documentation is available via the Semantic Web Company (SWC) website.

The PoolParty API gives you a set of pre-defined commands covering a wide variety of methods to manage data in your PoolParty server. The API is RESTful, so commands are handled using the http protocol; basically, a command is assembled in this general form:

http://[your-poolparty-server-address.com]/PoolParty/[path]/[command]?[parameters]

and then sent as either GET or POST requests. The response comes back in the form of (usually) a JSON package.

Example: getting a list of projects

Suppose you want to retrieve a list of the taxonomy projects on your server. You need to use the projects method:

http://tellura.poolparty.biz/PoolParty/api/projects

If you want to try this you will need to replace tellura.poolparty.biz with your own PoolParty server. You will be challenged with a login prompt if you are not already connected to the server in that browser. The response comes back as a list of results in the browser (exactly how this appears will vary from one browser to another):

This is a fairly typical JSON response; a string of text containing a set of parameters and their values. Most software development systems have tools for inspecting and extracting values from JSON strings.

Example: getting a hierarchical list of concepts from a concept scheme

PoolParty organises its data in projects. Each project contains one or more concept schemes. Think of a concept scheme as a container for your taxonomy concepts. So if you have a set of concepts representing countries, you would put them into a concept scheme called Countries. You can build a collection of projects, each with its own collection of concept schemes, and this confers a lot of flexibility in how you manage your taxonomy data.

However, we're focusing on technical details here. Suppose I have a concept scheme called Nutrition which contains a hierarchical set of concepts that represent different types of food. I can retrieve all of the food concepts, arranged in a hierarchy, using the subtree API method. For this method, I need the project id for the PoolParty project (in this case, 1DDFFAF3-A3D8-0001-199C-18E0E6001315), and I need the URI for the starting point of the subtree. The subtree method actually allows you to retrieve the subtree from any point in a project, so you need to specify that point using its URI. Collecting those together I get this as the API command. In this case I'm using the URI http://tellura.poolparty.biz/vocabulary/HealthExerciseandNutrition/0 for a concept scheme with the title "Nutrition".

http://tellura.poolparty.biz/PoolParty/api/thesaurus/1DDFFAF3-A3D8-0001-199C-18E0E6001315/subtree?root=http://tellura.poolparty.biz/vocabulary/HealthExerciseandNutrition/0

I can put this in the URL field in my browser, and this is the (radically trimmed) result.

[ {
  "concept" : {
    "uri" : "http://tellura.poolparty.biz/HealthExerciseandNutrition/46",
    "prefLabel" : "Drinks",
    "narrowers" : 
    [ "http://tellura.poolparty.biz/HealthExerciseandNutrition/47", 
      "http://tellura.poolparty.biz/HealthExerciseandNutrition/48" ]
  },
  "narrowers" : [ {
    "concept" : {
      "uri" : "http://tellura.poolparty.biz/HealthExerciseandNutrition/48",
      "prefLabel" : "Non-alcoholic drinks",
      "narrowers" : 
      [ "http://tellura.poolparty.biz/HealthExerciseandNutrition/24", 
          "http://tellura.poolparty.biz/HealthExerciseandNutrition/53", 
          "http://tellura.poolparty.biz/HealthExerciseandNutrition/54", 
          "http://tellura.poolparty.biz/HealthExerciseandNutrition/55", 
          "http://tellura.poolparty.biz/HealthExerciseandNutrition/56", 
          "http://tellura.poolparty.biz/HealthExerciseandNutrition/57", 
          "http://tellura.poolparty.biz/HealthExerciseandNutrition/58" ]
    },
    "narrowers" : [ {
      "concept" : {
        "uri" : "http://tellura.poolparty.biz/HealthExerciseandNutrition/24",
        "prefLabel" : "Milk"
      },
      "narrowers" : [ ]
[...]
  } ]
} ]

This is also a JSON string that I can unpack to use in my applications. You will see that the hierarchy is respected in this JSON string, so it can easily be reproduced in our own application UI.

Note that I need to be logged in to the server or I will get an authentication challenge, so if you want to run this you will need to replace the parameters with your own.

Of course it's a little impractical to run applications by typing commands into the url field, so at some point you are going to want to build your own UI and set up the scaffolding for connecting to PoolParty and adding your own parameters. In the next article I will show how to do this, and build an entire web application line by line.

Example of a desktop application: the Vocabulary Manager

On the whole web applications are the most useful when managing a web-based application like PoolParty. But it's equally possible to build desktop applications to do the same, with much more control over the user interface. For example, here is a similar list of projects displayed in our Vocabulary Manager application, which we developed using the cross-platform development tool Xojo. Detailed information on the currently-selected project is also displayed. I have greyed out client details in this screenshot to avoid identification of clients. This application illustrates how to use a desktop application to connect to a remote PoolParty instance and retrieve, disassemble and manage data stored on that server.

Note: this application will shortly be available to our PoolParty clients as a taxonomy management tool for administrators and developers. Get in touch if this is likely to be of interest to you.

That's it for this introductory article. I'll be coming back soon to describe more advanced API features and a fully worked example. You might also like to read our other articles on how to write software to use the SPARQL endpoints in PoolParty, such as this one.