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 aprevious
&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/