Getting started with the REST API

This guide describes what you’ll find on the Carbon LDP™ REST API documentation and how you can improve your learning experience by using all the resources we are providing. The REST API provides a way for applications to interact with the Carbon LDP™ platform using HTTP verbs (GET, POST, PUT, DELETE, etc.) and resources identified by URIs.

The REST API is a lower-level API than a Software Developing Kit (SDK) and doing things directly with the REST API is generally more tedious than with an SDK. However, understanding the REST API provides insight into how the platform works and can be advantageous in certain scenarios.

Previous knowledge

In this documentation, we’ll use different scenarios to go through the REST API methods, detailing the different headers and basic request bodies you can use to interact with Carbon LDP™. In order to achieve this, examples for requests generated are included to detail every interaction you can have with the Carbon LDP™ platform.

Note that Carbon LDP™ can handle requests issued using JSON-LD, TriG, Turtle, and RDF XML. Nevertheless, since we want to keep the documentation simple, the examples provided use only JSON-LD or TriG. For this reason you might want to check the JSON-LD and TriG specifications the World Wide Web Consortium (W3C) has developed and to which Carbon LDP complies.

Recommended tools

Since this guide focuses on the REST API, you’ll need a tool that can help you create and send HTTP requests. We recommend Postman. It’s a great tool, it’s free, and it’s the one we’ll be featuring in this guide. But feel free to use the tool you’re most comfortable with.

Also, we have created a Postman Collection with all the examples featured in this documentation. Feel free to import it and try all the examples yourself.

Note: This guide assumes the typical host and port for a local dev environment, localhost:8083. If your host and port differs, you’ll need to make adjustments when using the given examples.

About the documentation

Let us give you a brief introduction on what you’ll find when using our documentation.

About the request examples.

Whenever an example is presented on how to make a request to the platform it will follow a basic structure. The request will be described listing the method to use, the end point where the request will be made, and the headers and body it should include. Not all requests should include a body; whenever this is not needed, it will not be outlined. Nevertheless, whenever a request body is included it will be in both JSON-LD or TriG formats.

Following this, you’ll find a section detailing all the headers and the content of the request body. Refer to the external links in case you don’t understand anything from these explanations. Finally, a brief explanation of the response you should get for each request is also included.

The more you know …

Throughout the documentation you will find some messages that look like this:

The more you know…

Some interesting fact about Carbon LDP™ and Linked Data.

 

These boxes include some complementary information which gives you a more in depth knowledge on how Carbon LDP™ works. If you are new to Linked Data some of the concepts included in them might not result familiar. Not to worry; as mentioned, this is complementary information. You’ll be fine using Carbon LDP™’s REST API without a complete understanding of the complementary concepts.

We recommend that you initially read the Object and Interaction Models to familiarize yourself with the basic concepts Carbon LDP™ uses. Afterwards, we encourage that you continue with the rest of the documentation which contains practical examples on how to interact with these concepts through REST methods.

Conclusion

This guide described the basic knowledge and tools we believe you might need to get the most out of this guide. Remember that normally, developers will prefer use of the Carbon LDP™ Workbench (GUI) and an SDK, which together simplify the process of building an app. Still, all functions of the platform can be accessed through the REST API and those developers who understand the REST API may find it advantageous to use in some cases.