Skip to content

Commit 54ef968

Browse files
azmeukazmeuk
committed
doc: tutorial improvements
1 parent 406f7a5 commit 54ef968

File tree

2 files changed

+164
-1
lines changed

2 files changed

+164
-1
lines changed

‎doc/tutorial.rst‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,17 @@ Tutorial
33

44
The :ref:`cli` command allows you to interact with a SCIM server.
55

6+
.. tip::
7+
8+
If you want to test scim2-cli with a real SCIM server, you can install and run `scim2-server <https://github.com/python-scim/scim2-server>`__:
9+
10+
.. code-block:: shell
11+
12+
$ pip install scim2-server
13+
$ scim2-server
14+
15+
Then you have a functional SCIM server available at http://127.0.0.1:8080 that you can use to test the different commands.
16+
617
Basic parameters
718
----------------
819

@@ -76,12 +87,164 @@ You can store those data locally and reuse them for future command runs thanks t
7687
7788
Query and search resources
7889
--------------------------
90+
7991
The :ref:`query` and :ref:`search` commands can be used to look for resources.
8092
:ref:`query` performs ag `GET` request on the resources endpoint, while :ref:`search` performs a `POST` request on the ``/.search`` endpoint.
8193
Both commands take similar options such as :option:`--count <scim-query.--count>` or :option:`--attributes <scim-query.--attributes>`.
8294
An exhaustive list of options can be found on the :doc:`reference`.
8395
:ref:`query` can also take a :option:`RESOURCE_TYPE <scim-query.RESOURCE_TYPE>` and a :option:`ID <scim-query.ID>` parameters.
8496

8597
- If none are set, all the resources of the server are queried.
98+
99+
.. code-block:: console
100+
:caption: Querying all the resources from the server.
101+
102+
$ scim query
103+
{
104+
"schemas": [
105+
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
106+
],
107+
"totalResults": xx,
108+
"startIndex": 1,
109+
"itemsPerPage": 50,
110+
"Resources": [...]
111+
}
86112
- If :option:`RESOURCE_TYPE <scim-query.RESOURCE_TYPE>` and :option:`ID <scim-query.ID>` is unset, all the resource of the kind passed in parameter are returned.
113+
114+
.. code-block:: console
115+
:caption: Querying all the users from the server.
116+
117+
$ scim query user
118+
{
119+
"schemas": [
120+
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
121+
],
122+
"totalResults": xx,
123+
"startIndex": 1,
124+
"itemsPerPage": 50,
125+
"Resources": [...]
126+
}
127+
87128
- If both options are set, the very resource with the ID are returned.
129+
130+
.. code-block:: console
131+
:caption: Querying the user with the ID `38b044dd95624c4186f5614fca30305d`
132+
133+
$ scim query user 38b044dd95624c4186f5614fca30305d
134+
{
135+
"schemas": [
136+
"urn:ietf:params:scim:schemas:core:2.0:User",
137+
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
138+
],
139+
"id": "38b044dd95624c4186f5614fca30305d",
140+
"meta": {
141+
"resourceType": "User",
142+
"created": "2024-12-05T16:08:51.896646Z",
143+
"lastModified": "2024-12-05T16:08:51.896646Z",
144+
"location": "http://scim.example/v2/Users/38b044dd95624c4186f5614fca30305d",
145+
"version": "W/\"637b1ce03c010cd55fe45b6f7be2247b5159b135\""
146+
},
147+
"userName": "bjensen@example.com"
148+
}
149+
Create and replace resources
150+
----------------------------
151+
152+
The :ref:`create` and :ref:`replace` commands can be used to edit resources.
153+
154+
Options for those commands are dynamically generated, depending on the resource attributes available on the server.
155+
For instance, for the :class:`~scim2_models.User` resource, you have a ``--user-name`` option.
156+
You can have a look at the exhaustive list of options by running ``scim create user --help``.
157+
158+
.. code-block:: console
159+
:caption: Creation of an user.
160+
161+
$ scim create user --user-name bjensen@example.com
162+
{
163+
"schemas": [
164+
"urn:ietf:params:scim:schemas:core:2.0:User",
165+
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
166+
],
167+
"id": "38b044dd95624c4186f5614fca30305d",
168+
"meta": {
169+
"resourceType": "User",
170+
"created": "2024-12-05T16:08:51.896646Z",
171+
"lastModified": "2024-12-05T16:08:51.896646Z",
172+
"location": "http://scim.example/v2/Users/38b044dd95624c4186f5614fca30305d",
173+
"version": "W/\"637b1ce03c010cd55fe45b6f7be2247b5159b135\""
174+
},
175+
"userName": "bjensen@example.com"
176+
}
177+
178+
Delete resources
179+
----------------
180+
181+
The :ref:`delete` command allows you to delete resources.
182+
183+
.. code-block:: console
184+
:caption: Deletion of an user.
185+
186+
$ scim delete user 38b044dd95624c4186f5614fca30305d
187+
188+
Perform a SCIM compliance test
189+
------------------------------
190+
191+
The :ref:`test` command runs a series of resource creation, edition and deletions to check that your server complies with the SCIM specifications.
192+
See the :doc:`scim2-tester documentation <scim2_tester:index>` for more details on which tests are performed.
193+
194+
.. code-block:: console
195+
:caption: SCIM compliance test
196+
197+
$ scim test
198+
Performing a SCIM compliance check on http://localhost:8080 ...
199+
SUCCESS check_service_provider_config_endpoint
200+
SUCCESS check_query_all_resource_types
201+
SUCCESS check_query_resource_type_by_id
202+
Successfully accessed the /ResourceTypes/User endpoint.
203+
SUCCESS check_query_resource_type_by_id
204+
Successfully accessed the /ResourceTypes/Group endpoint.
205+
SUCCESS check_access_invalid_resource_typ
206+
...
207+
208+
JSON input
209+
----------
210+
211+
scim2-cli will also read input data from the standard input.
212+
This can be used to send custom payloads to the SCIM server.
213+
214+
When user with :ref:`query` and :ref:`search`, the input value must be a JSON representation of a :class:`~scim2_models.SearchRequest` object:
215+
216+
.. code-block:: console
217+
:caption: Search of an user by passing a custom payload.
218+
219+
$ echo '{"startIndex": 50, "count": 10}' | scim query user
220+
{
221+
"schemas": [
222+
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
223+
],
224+
"totalResults": xx,
225+
"startIndex": 50,
226+
"itemsPerPage": 10,
227+
"Resources": [...]
228+
}
229+
230+
When used with :ref:`create` and :ref:`replace`, no subcommand is needed and the endpoint is guessed from the payload.
231+
232+
.. code-block:: console
233+
:caption: Creation of an user by passing a custom payload.
234+
235+
$ echo '{"userName": "bjensen@example.com", "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"]}' | scim create
236+
{
237+
"schemas": [
238+
"urn:ietf:params:scim:schemas:core:2.0:User",
239+
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
240+
],
241+
"id": "38b044dd95624c4186f5614fca30305d",
242+
"meta": {
243+
"resourceType": "User",
244+
"created": "2024-12-05T16:08:51.896646Z",
245+
"lastModified": "2024-12-05T16:08:51.896646Z",
246+
"location": "http://scim.example/v2/Users/38b044dd95624c4186f5614fca30305d",
247+
"version": "W/\"637b1ce03c010cd55fe45b6f7be2247b5159b135\""
248+
},
249+
"userName": "bjensen@example.com"
250+
}

‎uv.lock‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)