This document describes how to communicate with an OpenPLM server to build a plugin.
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.
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"}
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().
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
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
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.
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
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
Query used to authenticate an user.
Url : | server/api/login/ |
---|---|
Type : | POST |
Login required: | no |
Implemented by: | |
Paramètres: | |
Returned fields: | |
|
|
Fail if: | user does not exist or user is inactive |
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() |
Query used to get all the subtypes of PLMObject managed by the server.
Url : | server/api/types/ |
---|---|
Type : | GET |
Login required: | yes |
Implemented by: | |
Returned fields: | |
|
Query used to get all the types of Part managed by the server.
Url : | server/api/parts/ |
---|---|
Type : | GET |
Login required: | yes |
Implemented by: | |
Returned fields: | |
|
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: | |
Returned fields: | |
|
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: | |
Get params: |
|
Returned fields: | |
|
Query used to create an object
Url : | server/api/create/ |
---|---|
Type : | POST |
Login required: | yes |
Implemented by: | |
Post params: |
|
Returned fields: | |
|
Query used to get available fields to perform a search
Url : | server/api/search_fields/typename/ |
---|---|
Type : | GET |
Login required: | yes |
Implemented by: | |
Returned fields: | |
|
Query used to fields need to create an object
Url : | server/api/creation_fields/typename/ |
---|---|
Type : | GET |
Login required: | yes |
Implemented by: | |
Returned fields: | |
|
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: | |
Returned fields: | |
|
In the following queries, part_id is a the id (an integer) of a Part
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 |
In the following queries, doc_id is a the id (an integer) of a Document
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: | |
Returned fields: | |
|
Make a new revision of the document
Url : | server/api/object/doc_id/revise/ |
---|---|
Type : | POST |
Login required: | yes |
Implemented by: | |
Post params: |
|
Returned fields: | |
|
Returns a possible new revision for the document.
Url : | server/api/object/doc_id/next_revision/ |
---|---|
Type : | GET |
Login required: | yes |
Implemented by: | |
Returned fields: | |
|
Returns True if the document can be revised.
Url : | server/api/object/doc_id/is_revisable/ |
---|---|
Type : | GET |
Login required: | yes |
Implemented by: | |
Returned fields: | |
|
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 |
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: | |
Post param: | filename |
Returned fields: | |
|
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 |
In the following queries, df_id is the id (an integer) of a DocumentFile.
Returns True if the file is locked.
Url : | server/api/object/doc_id/is_locked/df_id/ |
---|---|
Type : | GET |
Login required: | yes |
Implemented by: | |
Returned fields: | |
|
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 |
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 |
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 |
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 |
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 |