Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
tutorial:adm:api_requirements [2019/10/07 10:04] – doischerttutorial:adm:api_requirements [2025/11/06 14:26] (current) – poulm
Line 1: Line 1:
 ====== API - Requirements for a system to be connected ====== ====== API - Requirements for a system to be connected ======
 +
 This tutorial is intended as a guide for an administrator/architect planning to connect a system to CzechIdM. In order to connect a system to CzechIdM, there are some minimal requirements on the system's API. This tutorial is intended as a guide for an administrator/architect planning to connect a system to CzechIdM. In order to connect a system to CzechIdM, there are some minimal requirements on the system's API.
  
-CzechIdM supports [[devel:documentation:systems:dev:supported-connectors| many connectors]] and many others can be developed. Thus one can connect virtually any system to CzechIdM. In general, if a system's API supports operations described below, it can be connected to CzechIdM.+CzechIdM supports [[:devel:documentation:systems:dev:supported-connectors|many connectors]] and many others can be developed. Thus one can connect virtually any system to CzechIdM. In general, if a system's API supports operations described below, it can be connected to CzechIdM.
  
 ===== A source system or managed system? ===== ===== A source system or managed system? =====
Line 9: Line 10:
  
 ==== a) Source systems - Synchronization ==== ==== a) Source systems - Synchronization ====
-{{ :tutorial:adm:source_system.png |}} 
-Clearly, for fetching data into CzechIdM, the connected system must be able to provide it. As a minimum, it must provide the list of all items and one item by its ID: 
  
-^ Operation  ^ Description   ^ Operation parameters   ^ Output ^ +{{  .:source_system.png  }}Clearly, for fetching data into CzechIdM, the connected system must be able to provide it. As a minimum, it must provide the list of all items and one item by its ID: 
-| List All | Operation should provide list of all objects in your system, at least their IDs    | | List of all objects, e.g. Identities| + 
-| Get Object | When CzechIdM want to load one specific user  | id - identifier of user needed | One specific object  |+^Operation  ^Description  ^Operation parameters  ^Output| 
 +|List All|Operation should provide list of all objects in your system, at least their IDs  | |List of all objects, e.g. Identities| 
 +|Get Object|When CzechIdM want to load one specific user  |id - identifier of user needed|One specific object  |
  
 The following operation is not a must, but it's useful when synchronizing the Czech IdM data with outside data, but only the data that has changed since the last synchronization run. It is typically based on the value of some special attribute like LastUpdateTime. It is especially useful in cases when there are many objects to be synchronized (over thousands) and/or the connected system is somewhat slow. The following operation is not a must, but it's useful when synchronizing the Czech IdM data with outside data, but only the data that has changed since the last synchronization run. It is typically based on the value of some special attribute like LastUpdateTime. It is especially useful in cases when there are many objects to be synchronized (over thousands) and/or the connected system is somewhat slow.
  
-^ Operation       ^ Description                                                                                                                             ^ Operation parameters  ^ Output                                                                                                      ^ +^Operation  ^Description  ^Operation parameters  ^Output  | 
-| Search objects  | When one needs to synchronize object only specific objects, e.g. only those that have been changed since the last synchronization run.  | List of objects       | filter parameter - the token which is compared to some object attribute value - typically last update time  |+|Search objects  |When one needs to synchronize object only specific objects, e.g. only those that have been changed since the last synchronization run.  |List of objects  |filter parameter - the token which is compared to some object attribute value - typically last update time  | 
 + 
 +==== b) Managed systems - Provisioning ====
  
-====  b) Managed systems - Provisioning ==== +{{  .:end_system.png  }}
-{{ :tutorial:adm:end_system.png |}}+
  
-To be able to provide data to a connected system, its API must support the CRUD operations: +To be able to provide data to a connected system, its API must support the CRUD operations:
  
-^ Operation ^ Description ^ Operation parameters ^ Output  ^ +^Operation^Description^Operation parameters^Output  | | 
-| Get Object    | When CzechIdM wants to load one specific object  | id of the object | One specific object  | | +|Get Object  |When CzechIdM wants to load one specific object  |id of the object|One specific object  | | 
-| Delete Object | Delete object in a system   | id of the object we want to delete  | id of the deleted object | +|Delete Object|Delete object in a system  |id of the object we want to delete  |id of the deleted object| | 
-| Update Object | After changing some attribute of an identity in CzechIdM, we want to provide the change into the managed system. If you also want to update the user's permissions in the managed system (e.g. user's AD Groups), the operation should support it too or provide an operation that does the job on its own | id of the user we want to update | id - identifier of the updated object | | +|Update Object|After changing some attribute of an identity in CzechIdM, we want to provide the change into the managed system. If you also want to update the user's permissions in the managed system (e.g. user's AD Groups), the operation should support it too or provide an operation that does the job on its own|id of the user we want to update|id - identifier of the updated object| | 
-| Create Object | Having created a new identity in CzechIdM, we want it in the managed system, too. This operation should work both with one input parameter (id) and without it | id of the object | id - if no input parameter has been given |+|Create Object|Having created a new identity in CzechIdM, we want it in the managed system, too. This operation should work both with one input parameter (id) and without it|id of the object|id - if no input parameter has been given| |
  
 If still in doubt, look at the example below. It might give you a better clue of what it should look like. If still in doubt, look at the example below. It might give you a better clue of what it should look like.
Line 36: Line 38:
 ===== Example of REST ===== ===== Example of REST =====
  
-If you want to connect your system via REST, just prepare the endpoint as described and we can use our REST connector. It supports both provisioning and synchronization. +If you want to connect your system via REST, just prepare the endpoint as described and we can use our REST connector. It supports both provisioning and synchronization.
  
-^ Endpoint ^ Operation type ^ Corresponding operation  ^ Input Parameters  ^ Description ^  Output  ^  +^Endpoint^Operation type^Corresponding operation  ^Input Parameters  ^Description^  Output  | 
-| /users   | Get    | List All                 |      | This endpoints returns information about all identities in the system. | list of all users |  +|/users  |Get  |List All  |   |This endpoints returns information about all identities in the system.|list of all users| 
-| /users/{id}  | Delete | Delete Object            | ID   | This endpoint is used for deleting the existing users. |  | +|/users/{id}  |Delete|Delete Object  |ID  |This endpoint is used for deleting the existing users.|   | 
-| /users/{id} | Get  | Get Object                  | ID   | This endpoint returns information about a user with a specific identifier.  | one specific user | +|/users/{id}|Get  |Get Object  |ID  |This endpoint returns information about a user with a specific identifier.  |one specific user| 
-| /users/{id} | Put | Create/Update Object                  | ID   | This endpoint is used for updating existing users and creating new users with a known identifier in the system.  | ID (TODO check) | +|/users/{id}|Put|Create/Update Object  |ID  |This endpoint is used for updating existing users and creating new users with a known identifier in the system.  |ID (TODO check)| 
-| /users      | Post | Create Object               |      | This endpoint is used for creating new users in the system.  | ID (TODO check) |+|/users  |Post|Create Object  |   |This endpoint is used for creating new users in the system.  |ID (TODO check)|
  
 As you can see, the operations in this example fully correspond to the generic API description presented in the previous chapters. As you can see, the operations in this example fully correspond to the generic API description presented in the previous chapters.
Line 49: Line 51:
 ===== Example of DB Table ===== ===== Example of DB Table =====
  
-If you want to connect one DB table to CzechIdM, your DBMS must support CRUD operations (which it does, naturally :-)). So your main concern is to set the appropriate rights for the user that CzechIdM will use for the connection to DB. +If you want to connect one DB table to CzechIdM, your DBMS must support CRUD operations (which it does, naturally :-) ). So your main concern is to set the appropriate rights for the user that CzechIdM will use for the connection to DB.
  
-^ SQL operation ^ Corresponding operation  ^ Input Parameters ^  Output  ^  +^SQL operation^Corresponding operation  ^Input Parameters^  Output  | 
-| SELECT * FROM <TABLE>  | List All  | | list of all users |  +|SELECT * FROM <TABLE>  |List All  | |list of all users| 
-| DELETE FROM <TABLE> WHERE <ID> = {userID} | Delete | userID  |  | +|DELETE FROM <TABLE> WHERE <ID> = {userID}|Delete|userID  |   | 
-| SELECT * FROM <TABLE> WHERE <ID> = {userID} | Get Object                  | userID | one specific user | +|SELECT * FROM <TABLE> WHERE <ID> = {userID}|Get Object  |userID|one specific user| 
-| INSERT INTO <TABLE> VALUES <<ID>={userID},...> | Create                  | userID |  | +|INSERT INTO <TABLE> VALUES <<ID>={userID},…>|Create  |userID|   | 
-| UPDATE <TABLE> SET {attributes} WHERE <ID>={userID} | Update                  | attributes with values, userID |  |+|UPDATE <TABLE> SET {attributes} WHERE <ID>={userID}|Update  |attributes with values, userID|   |
  
-<TABLE> - connected DB Table +<TABLE> - connected DB Table <ID> - the name of the column with the unique identifier - e.g. primary key
-<ID> - the name of the column with the unique identifier - e.g. primary key+
  
 As you can see, the operations in this example fully correspond to the generic API description presented in the previous chapters. As you can see, the operations in this example fully correspond to the generic API description presented in the previous chapters.
Line 65: Line 66:
 ===== A source system's requirements: identities, contracts, organizations ===== ===== A source system's requirements: identities, contracts, organizations =====
  
-Each source system must contain some information based on the type of the connected system no matter the way in which the system is connected (REST, DB, CSV...). There three basic types of connected source systems: source of identities, source of contracts, and source of organizations.+Each source system must contain some information based on the type of the connected system no matter the way in which the system is connected (REST, DB, CSV…). There three basic types of connected source systems: source of identities, source of contracts, and source of organizations.
  
-====  Source of identities ====+==== Source of identities ====
  
-[[9.7:adm:identities|An identity]] is a set of information describing one person. In general, this information should be independent of the user's position within the organization so it shouldn't contain information about e. g. superiors or work positions.+[[:current:documentation:identities|An identity]] is a set of information describing one person. In general, this information should be independent of the user's position within the organization so it shouldn't contain information about e. g. superiors or work positions.
  
 Must contain: Must contain:
-  * ID - a unique identifier of the identity + 
-  * User name - a user name (or login) used to log in to CzechIdM+  * ID - a unique identifier of the identity (can be the same as Personal Number)
  
 Can contain (often contains): Can contain (often contains):
 +
   * Personal number   * Personal number
   * First name   * First name
Line 85: Line 87:
  
 Cannot contain: Cannot contain:
 +
   * Information about the user's position (belongs to contracts)   * Information about the user's position (belongs to contracts)
   * Information about the user's superiors (belongs to contracts)   * Information about the user's superiors (belongs to contracts)
  
-====  Source of contracts ====+==== Source of contracts ====
  
-[[9.7:documentation:identities:dev:contractual-relationship|A contract]] represents the relation of an identity to the company or organization. One identity can have multiple contracts and, as a result, different sets of permissions. +[[:current:documentation:contracts|A contract]] represents the relation of an identity to the company or organization. One identity can have multiple contracts and, as a result, different sets of permissions.
  
 Must contain: Must contain:
 +
   * Contract ID - a unique identifier of the contract   * Contract ID - a unique identifier of the contract
   * Identity ID - an identifier of the identity to which to contract belongs   * Identity ID - an identifier of the identity to which to contract belongs
  
 Can contain (often contains): Can contain (often contains):
 +
   * Valid from - the start of the validity of the contract   * Valid from - the start of the validity of the contract
   * Valid till - the end of the validity of the contract   * Valid till - the end of the validity of the contract
Line 104: Line 109:
   * Superior - either by Identity ID or Login   * Superior - either by Identity ID or Login
  
-====  Source of organizations ====+==== Source of organizations ====
  
-IdM can use [[9.7:adm:tree_structures|tree structures]] to represent the organizational structure of the company.+IdM can use [[:current:documentation:tree_structures|tree structures]] to represent the organizational structure of the company.
  
 Must contain: Must contain:
 +
   * Code - a unique identifier of the tree node   * Code - a unique identifier of the tree node
  
 Can contain: Can contain:
 +
   * Name of the tree node   * Name of the tree node
   * Superior element - can be null in which case it is considered to be the root element by default   * Superior element - can be null in which case it is considered to be the root element by default
 +
 +
  • by doischert