4. `http_api` — HTTP-API¶

This document describes how to communicate with an OpenPLM server to build a plugin.

4.1. How to make a query¶

You just have to make a POST or GET request to the server. All valid urls are described above.

Warning

You must set the user-agent to ‘openplm’, this is to prevent a CSRF attack. If an user click on a link related to the api, he will receive a 403 forbidden response. Moreover, a XMLHttpRequest object can not set the user agent if the script was launched from another domain.

4.2. Returned value¶

Results are returned in a JSON format. Each result contains at least two fields:

api_version

the api version (current : 1.1)

result

"ok" if no error occurred (i.e. the query was valid and succeed)

"error" if an error occurred

For example, a minimal result would be:

{"result": "ok", "api_version": "1.1"}

If an error occurred, an extra field is add:

error

a short description of the error

For example, a result could be:

{"result": "error", "api_version": "1.1", "error": "Oups an error occured"}

4.3. Authentication¶

Several queries require an authenticated user.

The authentication is based on Django module auth, so you need to make query with a cookies support.

To authenticated, see login().

4.4. Object fields¶

Some queries return a field which describes an object.

The fields are:

Field Description

id id of the object

type type of the object

reference reference of the object

revision revision of the object

name name of the object

4.5. Query fields¶

Some queries return a description of an object field, this description contains the following fields:

Field Description

name name of the field. Examples: "type", "reference", "wheels"

label verbose name more comprehensible for an user. Example: "Number of wheels"

type type of the field, the avalaible types are described above

initial initial (default) value for the field, may be None.

others fields see above

4.5.1. Available types¶

The available types are:

Type Description

"int" an integer (positive or negative)

"float" a float (positive or negative)

"decimal" a number with a restrictive format

"boolean" a boolean (True or False)

"text" a string

"choice" a type to choose among several values

If the type is "choice", another field, called "choices" is given. It contains a list of tuple (short_value, long_value) where short_value is the value for the server and long_value is the value for the user.

4.5.2. Optional fields¶

Some other fields may be given:

Field Associated types Description

min_value "int", "float", "decimale minimal value accepted by the field

max_value "int", "float", "decimale maximal value accepted by the field

min_length "text", minimal length of the field

max_length "text", maximal length of the field

4.6. File fields¶

Some queries return information about a file.

The fields are:

Field Description

id id of the file

filename name of the file (with its extension)

size size of the file in bytes

4.7. List of available queries¶

4.7.1. General queries¶

http_api.login()¶

Query used to authenticate an user.

Returned fields:
Url :	`server/api/login/`
Type :	POST
Login required:	no
Implemented by:	`plmapp.views.api.api_login()`
Parameters:	username (string) – the username of the user password (string) – the password of the user
	username the username passed in the POST query first_name the user’s first name last_name the user’s last name
Fail if:	user does not exist or user is inactive

http_api.testlogin()¶

Query used to test if an user is authenticated.

This query does not take any parameters and does not return any specific fields. If the user is authenticated, result would be set to "ok".

Url :	`server/api/testlogin/`
Type :	GET
Login required:	no
Implemented by:	`plmapp.views.api.test_login()`

http_api.types()¶

Query used to get all the subtypes of PLMObject managed by the server.

Returned fields:
Url :	`server/api/types/`
Type :	GET
Login required:	yes
Implemented by:	`plmapp.views.api.get_all_types()`
	types list of all types (string) sorted alphabetically (without `"plmobject"`)

See also

parts() and docs()

http_api.parts()¶

Query used to get all the types of Part managed by the server.

Returned fields:
Url :	`server/api/parts/`
Type :	GET
Login required:	yes
Implemented by:	`plmapp.views.api.get_all_parts()`
	types list of all types (string) sorted alphabetically

http_api.docs()¶

Query used to get all the types of Document managed by the server.

Returned fields:
Url :	`server/api/docs/` or `server/api/documents/`
Type :	GET
Login required:	yes
Implemented by:	`plmapp.views.api.get_all_docs()`
	types list of all types (string) sorted alphabetically

http_api.search()¶

Query used to perform a search on the objects stored on the server

Possible values for editable_only are:

true (the default) to return only editable objects

false to return all objects

Possible values for with_file_only are:

true (the default) to return only documents with at least one file

false to return all documents

Returned fields:
Url :	`server/api/search/[editable_only/[with_file_only/]]`
Type :	GET
Login required:	yes
Implemented by:	`plmapp.views.api.search()`
Get params:	type (required) a valid type (see `types()` to get a list of types) others params see `search_fields()`
	objects list of all objects matching the query, see Object fields.

http_api.create()¶

Query used to create an object

Returned fields:
Url :	`server/api/create/`
Type :	POST
Login required:	yes
Implemented by:	`plmapp.views.api.create()`
Post params:	type (required) a valid type (see `types()` to get a list of types) others params see `creation_fields()`
	object the object which has been created, see Object fields.

http_api.search_fields()¶

Query used to get available fields to perform a search

Returned fields:
Url :	`server/api/search_fields/typename/`
Type :	GET
Login required:	yes
Implemented by:	`plmapp.views.api.get_search_fields()`
	fields the list of fields available to perform a search on the objects of type typename, see Query fields.

http_api.creation_fields()¶

Query used to fields need to create an object

Returned fields:
Url :	`server/api/creation_fields/typename/`
Type :	GET
Login required:	yes
Implemented by:	`plmapp.views.api.get_creation_fields()`
	fields the list of fields need to create an object of type typename, see Query fields.

http_api.get()¶

New in version 1.1.

Returns description of an object (part or document) identified by its id.

Returned fields:
Url :	`server/get/object_id/`
Type :	GET
Login required:	yes
Implemented by:	`plmapp.views.api.get_object()`
	object dictionary describing the object, see Object fields.

4.7.2. Part queries¶

In the following queries, part_id is a the id (an integer) of a Part

http_api.attached_documents()¶

New in version 1.1.

Returns the list of attached parts.

Returned fields:
Url :	`server/api/object/part_id/attached_documents/`
Type :	GET
Login required:	yes
Implemented by:	`plmapp.views.api.get_attached_documents()`
	parts, a list of dictionaries describing attached documents

4.7.3. Document queries¶

In the following queries, doc_id is a the id (an integer) of a Document

http_api.files()¶

Returns the list of files associated to the document. If all/ is given, all files are returned, otherwise, only unlocked files are returned.

Returned fields:
Url :	`server/api/object/doc_id/files/[all/]`
Type :	GET
Login required:	yes
Implemented by:	`plmapp.views.api.get_files()`
	files the list of files of the document, see File fields.

http_api.revise()¶

Make a new revision of the document

Returned fields:
Url :	`server/api/object/doc_id/revise/`
Type :	POST
Login required:	yes
Implemented by:	`plmapp.views.api.revise()`
Post params:	revision new revision of the document
	doc the new document, see Object fields files the list of files of the new document, see File fields.

http_api.next_revision()¶

Returns a possible new revision for the document.

Returned fields:
Url :	`server/api/object/doc_id/next_revision/`
Type :	GET
Login required:	yes
Implemented by:	`plmapp.views.api.next_revision()`
	revision the new revision (may be an empty string)

http_api.is_revisable()¶

Returns True if the document can be revised.

Returned fields:
Url :	`server/api/object/doc_id/is_revisable/`
Type :	GET
Login required:	yes
Implemented by:	`plmapp.views.api.is_revisable()`
	revisable boolean, True if the document can be revised.

http_api.attach_to_part()¶

Links the document with the part identified by part_id

Returned fields:
Url :	`server/api/object/doc_id/attach_to_part/part_id/`
Type :	GET
Login required:	yes
Implemented by:	`plmapp.views.api.attach_to_part()`
	None

http_api.add_file()¶

Adds a file to the document, the request must have the attribute enctype="multipart/form-data".

If the url ends with thumbnail/ a thumbnail will be generated by openPLM.

Returned fields:
Url :	`server/api/object/doc_id/add_file/[thumbnail/]`
Type :	POST
Login required:	yes
Implemented by:	`plmapp.views.api.add_file()`
Post param:	filename
	doc_file the file that has been had, see File fields.

http_api.attached_parts()¶

New in version 1.1.

Returns the list of attached parts.

Returned fields:
Url :	`server/api/object/doc_id/attached_parts/`
Type :	GET
Login required:	yes
Implemented by:	`plmapp.views.api.get_attached_parts()`
	parts, a list of dictionaries describing attached parts

4.7.3.1. Document file queries¶

In the following queries, df_id is the id (an integer) of a DocumentFile.

http_api.is_locked()¶

Returns True if the file is locked.

Returned fields:
Url :	`server/api/object/doc_id/is_locked/df_id/`
Type :	GET
Login required:	yes
Implemented by:	`plmapp.views.api.is_locked()`
	locked boolean, True if the file is locked.

http_api.lock()¶

Locks the file

Returned fields:
Url :	`server/api/object/doc_id/lock/df_id/` or `server/api/object/doc_id/checkout/df_id/`
Type :	GET
Login required:	yes
Implemented by:	`plmapp.views.api.check_out()`
	None

http_api.unlock()¶

Unlocks the file

Returned fields:
Url :	`server/api/object/doc_id/unlock/df_id/`
Type :	GET
Login required:	yes
Implemented by:	`plmapp.views.api.unlock()`
	None

http_api.checkin()¶

Updates (checks-in) the file, the request must have the attribute enctype="multipart/form-data".

If the url ends with thumbnail/ a thumbnail will be generated by openPLM.

Returned fields:
Url :	`server/api/object/doc_id/checkin/df_id/[thumbnail/]`
Type :	POST
Login required:	yes
Implemented by:	`plmapp.views.api.check_in()`
Post param:	filename
	None

http_api.add_thumbnail()¶

Adds a thumbnail to the file, the request must have the attribute enctype="multipart/form-data".

Returned fields:
Url :	`server/api/object/doc_id/add_thumbnail/df_id/`
Type :	POST
Login required:	yes
Implemented by:	`plmapp.views.api.add_thumbnail()`
Post param:	filename
	None

http_api.lock_files()¶

New in version 1.1.

Locks several files in one transactional block.

Files are set by a POST parameter, files which must be a json list of ids of DocumentFile to be locked.

If one file can not be locked, no files are locked.

Returned fields:
Url :	`server/api/lock_files`
Type :	POST
Login required:	yes
Implemented by:	`plmapp.views.api.lock_files()`
Post param:	files, a list of ids of document files
	None

Table Of Contents

Previous topic

Next topic

This Page

Languages

External links

Previous versions

4. `http_api` — HTTP-API¶

4.1. How to make a query¶

4.2. Returned value¶

4.3. Authentication¶

4.4. Object fields¶

4.5. Query fields¶

4.5.1. Available types¶

4.5.2. Optional fields¶

4.6. File fields¶

4.7. List of available queries¶

4.7.1. General queries¶

4.7.2. Part queries¶

4.7.3. Document queries¶

4.7.3.1. Document file queries¶

Field	Description
id	id of the object
type	type of the object
reference	reference of the object
revision	revision of the object
name	name of the object

Field	Description
name	name of the field. Examples: `"type"`, `"reference"`, `"wheels"`
label	verbose name more comprehensible for an user. Example: `"Number of wheels"`
type	type of the field, the avalaible types are described above
initial	initial (default) value for the field, may be None.
others fields	see above

Type	Description
`"int"`	an integer (positive or negative)
`"float"`	a float (positive or negative)
`"decimal"`	a number with a restrictive format
`"boolean"`	a boolean (True or False)
`"text"`	a string
`"choice"`	a type to choose among several values

Field	Associated types	Description
min_value	`"int"`, `"float"`, `"decimale`	minimal value accepted by the field
max_value	`"int"`, `"float"`, `"decimale`	maximal value accepted by the field
min_length	`"text"`,	minimal length of the field
max_length	`"text"`,	maximal length of the field

Field	Description
id	id of the file
filename	name of the file (with its extension)
size	size of the file in bytes

Navigation

Table Of Contents

Previous topic

Next topic

This Page

Quick search

Languages

External links

Previous versions

4. http_api — HTTP-API¶

4.1. How to make a query¶

4.2. Returned value¶

4.3. Authentication¶

4.4. Object fields¶

4.5. Query fields¶

4.5.1. Available types¶

4.5.2. Optional fields¶

4.6. File fields¶

4.7. List of available queries¶

4.7.1. General queries¶

4.7.2. Part queries¶

4.7.3. Document queries¶

4.7.3.1. Document file queries¶

Navigation

4. `http_api` — HTTP-API¶