User Tools

Site Tools

:: Latest version ::

latest:advancedtopics:rest_json

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
latest:advancedtopics:rest_json [2019/11/14 15:02]
vdumas [Presentation]
latest:advancedtopics:rest_json [2020/04/15 15:23] (current)
Line 3: Line 3:
 ===== Presentation ===== ===== Presentation =====
 iTop provides a REST/JSON interface which allows third party applications to remotely interact with iTop for retrieving, creating or updating iTop objects. This interface is based on a set of simple HTTP POST requests. The data passed to and retrieved from iTop are encoded in JSON using the UTF-8 character set. iTop provides a REST/JSON interface which allows third party applications to remotely interact with iTop for retrieving, creating or updating iTop objects. This interface is based on a set of simple HTTP POST requests. The data passed to and retrieved from iTop are encoded in JSON using the UTF-8 character set.
- 
- 
  
  
Line 28: Line 26:
 **Since iTop 2.5.0**, the access to the REST web services is restricted to the users having the profile ''​REST Services User''​. ​ **Since iTop 2.5.0**, the access to the REST web services is restricted to the users having the profile ''​REST Services User''​. ​
 </​note>​ </​note>​
 +
 +  * As REST web services can easily be put in a loop, users must have ''​write access''​ **and** ''​bulk write''​ on the classes they modify. Applying a stimulus is a modification.
   * Make sure that your scripts using REST web services have ''​REST Services User''​ profile.   * Make sure that your scripts using REST web services have ''​REST Services User''​ profile.
   * Your users with ''​Administrator''​ profile **won'​t** have access to REST without this ''​REST Services User''​ additional profile.   * Your users with ''​Administrator''​ profile **won'​t** have access to REST without this ''​REST Services User''​ additional profile.
 If you want to emulate the  previous behavior (i.e. allow any user to access the REST web services) add the configuration parameter ''​secure_rest_services''​ and set it to ''​false''​. If you want to emulate the  previous behavior (i.e. allow any user to access the REST web services) add the configuration parameter ''​secure_rest_services''​ and set it to ''​false''​.
  
-<note warning>​Depending on how you test REST/JSON API, you may need to enable **url** within the [[2_6_0:​admin:​user_authentication_options#​logon_types|allowed_login_types]] set in the Configuration file of your iTop</​note>​ +<note warning>​Depending on how you test REST/JSON API, you may need to enable **url** within the [[2_7_0:​admin:​user_authentication_options#​logon_types|allowed_login_types]] set in the Configuration file of your iTop</​note>​
- +
-__Parameters:​__ ​+
  
 +__Parameters:​__
 Let's have a look at all the parameters of this HTTP service: Let's have a look at all the parameters of this HTTP service:
  
Line 104: Line 103:
 | 4 | INVALID_JSON | The input structure is not a valid JSON string | | 4 | INVALID_JSON | The input structure is not a valid JSON string |
 | 5 | MISSING_AUTH_USER | The parameter '​auth_user'​ is missing | | 5 | MISSING_AUTH_USER | The parameter '​auth_user'​ is missing |
-| 6 | MISSING_AUTH_PWD | The parameter '​auth_pwd'​ is missing or you are using [[2_6_0:​admin:​user_authentication_options#​logon_types|url login type]] and it's not allowed on the Configuration file of your iTop |+| 6 | MISSING_AUTH_PWD | The parameter '​auth_pwd'​ is missing or you are using [[2_7_0:​admin:​user_authentication_options#​logon_types|url login type]] and it's not allowed on the Configuration file of your iTop |
 | 10 | UNSUPPORTED_VERSION | No operation is available for the specified version | | 10 | UNSUPPORTED_VERSION | No operation is available for the specified version |
 | 11 | UNKNOWN_OPERATION | The requested operation is not valid for the specified version | | 11 | UNKNOWN_OPERATION | The requested operation is not valid for the specified version |
Line 340: Line 339:
  
 Passing the following ''​json_data'':​ Passing the following ''​json_data'':​
-<​code>​+<​code ​JavaScript>
 { {
    "​operation":​ "​core/​get",​    "​operation":​ "​core/​get",​
Line 351: Line 350:
 or, using another form of "​key":​ or, using another form of "​key":​
  
-<​code>​+<​code ​JavaScript>
 { {
    "​operation":​ "​core/​get",​    "​operation":​ "​core/​get",​
Line 360: Line 359:
 </​code>​ </​code>​
  
 +Since 2.6.1 ([[https://​github.com/​Combodo/​iTop/​pull/​25|PR #25]], thanks to Dennis Lassiter !), pagination is handled using two new parameters :
 +
 +  * limit (int): Amount of results to return (default: 0 = no limit)
 +  * page (int): Page number to return (cannot be < 1)
 +
 +Records ordering can be controlled using the classes/​class/​properties/​order datamodel XML node.
 +
 +Example :
 +
 +<code JavaScript>​
 +{
 +   "​operation":​ "​core/​get",​
 +   "​class":​ "​Person",​
 +   "​key":​ "​SELECT Person",​
 +   "​output_fields":​ "​friendlyname,​ email"
 +   "​limit":​ "​5",​
 +   "​page":​ "​2"​
 +}
 +</​code>​
 ==== Operation: core/create ==== ==== Operation: core/create ====
 Creates a new object of the given class Creates a new object of the given class
Line 581: Line 599:
 Here is the corresponding code: [[http://​jsfiddle.net/​U6qwK/​6/​|jsfiddle playground]] Here is the corresponding code: [[http://​jsfiddle.net/​U6qwK/​6/​|jsfiddle playground]]
  
 +Example of how you can integrate REST/JSON calls: [[2_7_0:​advancedtopics:​create_ticket#​using_bash_and_wget|using bash and wget]]
 ===== How to add services ===== ===== How to add services =====
 It is possible to extend the services by developping a module (or extension) that declares a class (included in your custom module) implementing the interface //​iRestServiceProvider//​. It is possible to extend the services by developping a module (or extension) that declares a class (included in your custom module) implementing the interface //​iRestServiceProvider//​.
Line 594: Line 612:
 | 2.0.3| 1.2| Fully handle the case logs (could be entirely read or written), Enums/GET giving the raw value not the localized label, Allow the HTTP basic authentication method, Added the verb core/​check_credentials,​ Improved the error reporting (missing authentication arguments, wrong class for writing a link set), Added the option *+ to output all the fields of the object (not only the fields of the queried class), Fixed the report on object deletion| | 2.0.3| 1.2| Fully handle the case logs (could be entirely read or written), Enums/GET giving the raw value not the localized label, Allow the HTTP basic authentication method, Added the verb core/​check_credentials,​ Improved the error reporting (missing authentication arguments, wrong class for writing a link set), Added the option *+ to output all the fields of the object (not only the fields of the queried class), Fixed the report on object deletion|
 | 2.2.0| 1.3| Verb get_related:​ added the options ''​redundancy''​ and ''​direction''​ to take into account the redundancy in the impact analysis. For security reasons, the use of REST/JSON webservices by user accounts with the profile ''​Portal User''​ **is now disabled**. If you use one of the webservices only to check the credentials of a user, adjust your code to use the ''​core/​check_credentials''​ operation. For security reasons, the operations ''​core/​get''​ and ''​core/​get_related''​ are now only allowed to users having the ''​bulk read''​ privilege on the specified class of objects.| | 2.2.0| 1.3| Verb get_related:​ added the options ''​redundancy''​ and ''​direction''​ to take into account the redundancy in the impact analysis. For security reasons, the use of REST/JSON webservices by user accounts with the profile ''​Portal User''​ **is now disabled**. If you use one of the webservices only to check the credentials of a user, adjust your code to use the ''​core/​check_credentials''​ operation. For security reasons, the operations ''​core/​get''​ and ''​core/​get_related''​ are now only allowed to users having the ''​bulk read''​ privilege on the specified class of objects.|
 +| 2.5.2, 2.6.1, 2.7.0 | 1.4 | Verb core/get : added pagination parameters limit and page |
latest/advancedtopics/rest_json.1573740166.txt.gz · Last modified: 2019/11/14 15:02 by vdumas

";