Welcome to the Unicat API tutorials.
We assume you're already familiar with Unicat, but if you're not, or you need to brush up a bit, please read The parts that make up Unicat first.
In this tutorial we'll connect to the Unicat server, and explain the results we'll get back.
We need two things - a project, and an API key.
From the project, we need its gid - a gid is a global identifier that is unique. You can find it if you're in the user interface for the project, in the address bar. But there's a quicker way, because we need an API key too.
The get the API key, an API user must be created for the project. You can do this from the Project settings workspace. If you select the API user, you can find the connection parameters - both the project gid and the API key to use.
ATTENTION: don't share this API key - it is an authentication token that gives access to the whole Unicat project, much like your username/password combination is.
First, we need to authenticate ourselves with the API key. If that is successful, we receive two things - a set of initialization data, and a JSON Web Token (JWT), that is used on subsequent API calls for authentication and authorization.
Note: don't share the JWT either please.
The authentication happens on the project's auth endpoint:
https://unicat.app/api/p/<project gid>/auth
where <project gid> is replaced by the actual project gid.
We have to do a POST request and provide the api_key.
curl -X POST -H "Content-Type: application/json" \
-d '{"api_key": "<your-api_key-here>"}' \
https://unicat.app/api/p/<project gid>/auth
We can look this up in the /api/p/<project gid>/auth reference documentation.
Calling this endpoint can give one of three results - a 400 Bad request (we didn't provide the api_key parameter), a 403 Forbidden (unknown user for this project), or a 200 Success if everything checks out.
In all cases, a JSON structure is returned with three properties, success (a true/false value), result (relevant information for your call, or an error result for the 400 and 403 cases), and data (result contains references to this data, where we get the complete data - or empty on errors).
Dive deeper into this in The basics for sending and retrieving data.
When the call was successful, we don't only get the JSON structure, we'll also get a JSON Web Token from the Authorization response header. We use this in subsequent calls, where we add a -H "Authorization: Bearer
These subsequent calls may in turn also return an updated Authorization response header when the token is refreshed, and we should use the fresh one for the next call.
A successful /auth call returns the same JSON data as any subsequent /init call - lists of all definitions, classes, fields, and layouts for the current project, and information about the current user and project, the other projects this user is part of, and the other users that are part of this project.
Specifics can again be found in the /api/p/<project gid>/auth reference documentation.
We're going to use a bit of Python to work through the result - feel free to translate to your language of choice.
…
json_response = json.loads(response.body)
success = json_response["success"]
if not success:
sys.exit(1)
result = json_response["result"]
data = json_response["data"]
print()
user = data["cc.users"][result["user"]]
project = data["cc.projects"][result["project"]]
print(project["name"], ":", user["name"])
for project_member in data["cc.projects_members"]:
if project_member["project_gid"] == project["gid"] and project_member["user_gid"] == user["gid"]:
print("roles": project_member["roles"])
print()
for definition_gid, definition in data["definitions"].items():
print(definition["name"])
print()
for class_gid, class_ in data["classes"].items():
print(class_["name"])
print()
for field_gid, field in data["fields"].items():
print(field["name"])
print()
The basic gist of it is that the result value holds mostly references (gids), and the data returned holds all resources with their properties, accessible by resource name plus the resource's gid (e.g. data["classes"]["<class gid>"]).
We have a work-in-progress Python SDK available, and a how-to on how to get started. See Use the Python SDK.
There's also documentation about building your own low-level API connector. Have a look at Create an API connector to help yourself on your way.