Table des matières

Sujet précédent

3. Cookbook

Sujet suivant

5. Modules (openPLM.plmapp package)

Cette page

Autres langues

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.

Url :

server/api/login/

Type :

POST

Login required:

no

Implemented by:

plmapp.views.api.api_login()

Paramètres:
  • username (string) – the username of the user
  • password (string) – the password of the user
Returned fields:
 
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.

Url :

server/api/types/

Type :

GET

Login required:

yes

Implemented by:

plmapp.views.api.get_all_types()

Returned fields:
 
types

list of all types (string) sorted alphabetically (without "plmobject")

Voir aussi

parts() and docs()

http_api.parts()

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

Url :

server/api/parts/

Type :

GET

Login required:

yes

Implemented by:

plmapp.views.api.get_all_parts()

Returned fields:
 
types

list of all types (string) sorted alphabetically

http_api.docs()

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

Url :

server/api/docs/ or server/api/documents/

Type :

GET

Login required:

yes

Implemented by:

plmapp.views.api.get_all_docs()

Returned fields:
 
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
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()

Returned fields:
 
objects

list of all objects matching the query, see Object fields.

http_api.create()

Query used to create an object

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()

Returned 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

Url :

server/api/search_fields/typename/

Type :

GET

Login required:

yes

Implemented by:

plmapp.views.api.get_search_fields()

Returned 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

Url :

server/api/creation_fields/typename/

Type :

GET

Login required:

yes

Implemented by:

plmapp.views.api.get_creation_fields()

Returned fields:
 
fields

the list of fields need to create an object of type typename, see Query fields.

http_api.get()

Introduit dans la version 1.1.

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

Url :

server/get/object_id/

Type :

GET

Login required:

yes

Implemented by:

plmapp.views.api.get_object()

Returned fields:
 
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()

Introduit dans la version 1.1.

Returns the list of attached parts.

Url :server/api/object/part_id/attached_documents/
Type :GET
Login required:yes
Implemented by:plmapp.views.api.get_attached_documents()
Returned fields:
 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.

Url :

server/api/object/doc_id/files/[all/]

Type :

GET

Login required:

yes

Implemented by:

plmapp.views.api.get_files()

Returned fields:
 
files

the list of files of the document, see File fields.

http_api.revise()

Make a new revision of the document

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

Returned fields:
 
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.

Url :

server/api/object/doc_id/next_revision/

Type :

GET

Login required:

yes

Implemented by:

plmapp.views.api.next_revision()

Returned fields:
 
revision

the new revision (may be an empty string)

http_api.is_revisable()

Returns True if the document can be revised.

Url :

server/api/object/doc_id/is_revisable/

Type :

GET

Login required:

yes

Implemented by:

plmapp.views.api.is_revisable()

Returned fields:
 
revisable

boolean, True if the document can be revised.

http_api.attach_to_part()

Links the document with the part identified by part_id

Url :server/api/object/doc_id/attach_to_part/part_id/
Type :GET
Login required:yes
Implemented by:plmapp.views.api.attach_to_part()
Returned fields:
 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.

Url :

server/api/object/doc_id/add_file/[thumbnail/]

Type :

POST

Login required:

yes

Implemented by:

plmapp.views.api.add_file()

Post param:

filename

Returned fields:
 
doc_file

the file that has been had, see File fields.

http_api.attached_parts()

Introduit dans la version 1.1.

Returns the list of attached parts.

Url :server/api/object/doc_id/attached_parts/
Type :GET
Login required:yes
Implemented by:plmapp.views.api.get_attached_parts()
Returned fields:
 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.

Url :

server/api/object/doc_id/is_locked/df_id/

Type :

GET

Login required:

yes

Implemented by:

plmapp.views.api.is_locked()

Returned fields:
 
locked

boolean, True if the file is locked.

http_api.lock()

Locks the file

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()
Returned fields:
 None
http_api.unlock()

Unlocks the file

Url :server/api/object/doc_id/unlock/df_id/
Type :GET
Login required:yes
Implemented by:plmapp.views.api.unlock()
Returned fields:
 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.

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
Returned fields:
 None
http_api.add_thumbnail()

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

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
Returned fields:
 None
http_api.lock_files()

Introduit dans la 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.

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
Returned fields:
 None