REST API introduction

Overview of REST APIs

The Portal REST API allows developers to hook into entities and objects that exist in Portal and though Portal to some 3rd parties integration. It is ideal for integrating with other 3rd Party systems for control and querying Portal without needing to use the plugin infrastructure.

There are currently two versions of the REST API. v1 (version 1) this API is documented here in these docs. v2 API is documented through Swagger and is available from Portal itself. To view this log in to Portal and if you have the correct credentials it will be under the Help navigation as REST API Reference.

Warning

All of /API/v1/ is deprecated and will be removed in Portal 5.0.0. Please see the V2 APIs for replacements if you are still using an /API/V1/ -endpoint.

Authorization

The authorization is checked using the standard Portal authentication mechanism, then each individual resource will have its own ACL on it for accessing as noted in the following documentation.

Note

With version 1 API the ?format=json is an override required to make things look decent in the browser (accept headers vary between browsers). Portal properly handles the Accept header. So the following will work properly:

curl -H "Accept: application/json" http://127.0.0.1:8000/api/entry/

But if you’re sure you want something else (or want to test in a browser), Portal lets you specify ?format=... when you really want to force a certain type.

Version 2 of the API will natively support accessing via web browser, and you can do content negotiation with Accept Headers.

Either authorize by logging in using a web browser and getting session credentials or use HTTP Basic Authentication

Serialization support

By default JSON is used. The extra optional formats are supported with version one of the API:

XML

Install - lxml (http://codespeak.net/lxml/) to use XML serializer

YAML

Install - pyyaml (http://pyyaml.org/) to use the YAML serializer

Entry points and Schema

To see the entry points and schemas follow the entry point which will point to the individual schemas

We will assume that you are running on localhost, and have a command line with curl installed.

Entry point:

curl http://localhost:8000/API/v1/

We get back data that looks like:

{"groupprofile": {"list_endpoint": "/API/v1/groupprofile/",

“schema”: “/API/v1/groupprofile/schema/”}, “mediabin”: {“list_endpoint”: “/API/v1/mediabin/”, “schema”: “/API/v1/mediabin/schema/”}, “standards/aspectratio”: {“list_endpoint”: “/API/v1/standards/aspectratio/”, “schema”: “/API/v1/standards/aspectratio/schema/”}, “standards/audiocodec”: {“list_endpoint”: “/API/v1/standards/audiocodec/”, “schema”: “/API/v1/standards/audiocodec/schema/”}, “standards/format”: {“list_endpoint”: “/API/v1/standards/format/”, “schema”: “/API/v1/standards/format/schema/”}, “standards/resolution”: {“list_endpoint”: “/API/v1/standards/resolution/”, “schema”: “/API/v1/standards/resolution/schema/”}, “standards/standard”: {“list_endpoint”: “/API/v1/standards/standard/”, “schema”: “/API/v1/standards/standard/schema/”}, “standards/videocodec”: {“list_endpoint”: “/API/v1/standards/videocodec/”, “schema”: “/API/v1/standards/videocodec/schema/”}, “theme”: {“list_endpoint”: “/API/v1/theme/”, “schema”: “/API/v1/theme/schema/”}, “user”: {“list_endpoint”: “/API/v1/user/”, “schema”: “/API/v1/user/schema/”}, “useraccountprofile”: {“list_endpoint”: “/API/v1/useraccountprofile/”, “schema”: “/API/v1/useraccountprofile/schema/”}, “userprofile”: {“list_endpoint”: “/API/v1/userprofile/”, “schema”: “/API/v1/userprofile/schema/”}}%

The entry point gives a schema URL to which we can try:

curl http://localhost:8000/API/v1/mediabin/schema/

Or we can get a list of MediaBin objects like:

curl http://localhost:8000/API/v1/mediabin/

Some things to note:

• By default, you get a paginated set of objects (20 per page is the default).
• In the meta, you get a previous & next. If available, these are URIs to the previous & next pages.
• You get a list of resources/objects under the objects key.
• Each resources/object has a resource_uri field that points to the detail view for that object.

To skip paginating:

curl http://localhost:8000/API/v1/mediabin/?limit=0

To get an object resource where the ID is 1:

curl http://localhost:8000/API/v1/mediabin/1/

To get a set of objects:

curl http://localhost:8000/API/v1/mediabin/set/1;3/