openapi.yaml 27.9 KB
Newer Older
1
openapi: 3.0.0
2
info:
3
  description: The FusionDirectory REST API
4
5
  version: 1.0.0
  title: FusionDirectory
6
  contact:
7
    email: contact@fusiondirectory.org
8
  license:
9
    name: GPL2+
10
servers:
11
  - url: 'http://localhost/fusiondirectory/rest.php/v1'
12
security:
13
  - session: []
14
tags:
15
16
  - name: authentification
    description: Authentification methods
17
18
  - name: objects
    description: 'List, get, create, delete objects'
19
20
  - name: attributes
    description: 'List, get, create, delete attributes'
21
22
  - name: multivaluated
    description: 'List, get, create, delete attributes'
23
24
  - name: types
    description: Get information on object types and tabs
25
26
  - name: recovery
    description: Use password recovery mecanism
27
28
29
paths:
  /login:
    post:
30
      operationId: login
31
32
33
      summary: Login to the API
      security: []
      tags:
34
        - authentification
35
36
      requestBody:
        content:
37
          application/json:
38
            schema:
39
              title: LoginRequest
40
              type: object
41
              properties:
42
43
                directory:
                  description: The LDAP directory to log into. Use /directories to get possible values.
44
                  type: string
45
                  example: "default"
46
47
48
                user:
                  description: The user to login as
                  type: string
49
                  example: "fd-admin"
50
51
52
                password:
                  description: The password to use
                  type: string
53
                  example: "password"
54
55
56
              required:
                - user
                - password
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
      responses:
        '200':
          description: An API token
          content:
            application/json:
              schema:
                type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: string
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
75
                $ref: '#/components/schemas/Error'
76
  /directories:
77
    get:
78
79
      summary: List possible values for directory parameter for login action
      operationId: listDirectories
80
      security: []
81
      tags:
82
        - authentification
83
84
      responses:
        '200':
85
          description: The list of LDAP directories that can be specified as directory parameter for /login endpoint
86
87
88
          content:
            application/json:
              schema:
89
90
                type: object
                additionalProperties:
91
                  type: string
92
93
94
              example: {
                        'default': 'default'
                      }
95
96
97
98
99
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
100
                $ref: '#/components/schemas/Error'
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
  /logout:
    post:
      operationId: logout
      summary: End the currently opened session
      tags:
        - authentification
      responses:
        '204':
          description: success
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
116
  /token:
117
    get:
118
      summary: Get session token for current session
119
      operationId: getToken
120
      tags:
121
        - authentification
122
123
124
125
126
127
      responses:
        '200':
          description: An API token
          content:
            application/json:
              schema:
128
                type: string
129
130
131
132
133
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
134
                $ref: '#/components/schemas/Error'
135
136
137
  /types:
    get:
      summary: List all types
138
      operationId: listTypes
139
140
141
142
143
144
145
146
      tags:
        - types
      responses:
        '200':
          description: A list of types
          content:
            application/json:
              schema:
147
                $ref: '#/components/schemas/TypeList'
148
149
150
151
152
        default:
          description: unexpected error
          content:
            application/json:
              schema:
153
154
                $ref: '#/components/schemas/Error'
  '/types/{type}':
155
156
    get:
      summary: Get informations on a type
157
      operationId: getTypeInfo
158
159
160
      tags:
        - types
      parameters:
161
        - $ref: '#/components/parameters/type'
162
163
      responses:
        '200':
164
          description: Information about the type
165
166
167
          content:
            application/json:
              schema:
168
                $ref: '#/components/schemas/Type'
169
170
171
172
173
        default:
          description: unexpected error
          content:
            application/json:
              schema:
174
175
176
177
                $ref: '#/components/schemas/Error'
  '/types/{type}/{tab}':
    get:
      summary: Get informations on a tab
178
      operationId: getTabInfo
179
180
181
      tags:
        - types
      parameters:
182
183
        - $ref: '#/components/parameters/type'
        - $ref: '#/components/parameters/tab'
184
185
      responses:
        '200':
186
          description: Information about the tab
187
188
189
190
191
192
193
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TabInfo'
              example: {
                        "sections": {
                          "main": {
194
                            "name": "Personal info",
195
                            "attrs": [
196
197
198
199
200
201
202
203
204
                              "personalTitle",
                              "fdNickName",
                              "fdBadge",
                              "dateOfBirth",
                              "gender",
                              "co",
                              "fdContractStartDate",
                              "fdContractEndDate",
                              "fdPhotoVisible"
205
206
                            ]
                          },
207
208
                          "contact": {
                            "name": "Contact",
209
                            "attrs": [
210
211
                              "fdSocialAccount",
                              "fdPrivateMail"
212
213
214
215
216
                            ]
                          }
                        },
                        "sections_order": [
                          "main",
217
                          "contact"
218
219
220
221
222
223
224
225
226
                        ]
                      }
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  '/objects/{type}':
227
228
    get:
      summary: Search objects of specific type
229
      operationId: listObjects
230
231
232
      tags:
        - objects
      parameters:
233
        - $ref: '#/components/parameters/type'
234
235
        - $ref: '#/components/parameters/base'
        - $ref: '#/components/parameters/filter'
236
237
238
        - name: attrs
          in: query
          required: false
239
240
241
242
243
          description: "The attributes to return: the keys must be the wanted attributes,
            and the values can be either 1, '*', 'b64' or 'raw' depending if you want a
            single value or an array of values. Other values are considered to be 1.
            'raw' means untouched LDAP value and is only useful for dns.
            'b64' means an array of base64 encoded values and is mainly useful for binary attributes."
244
245
          schema:
            type: object
246
          style: deepObject
247
          explode: true
248
249
250
          example:
            sn: 1
            title: "*"
251
252
253
254
255
256
        - name: scope
          in: query
          required: false
          description: The scope, defaults to subtree
          schema:
            type: string
257
258
            default: "subtree"
          example: "subtree"
259
260
261
262
263
264
        - name: templates
          in: query
          required: false
          description: Whether to search for templates instead of standard objects, defaults to false
          schema:
            type: boolean
265
266
            default: false
          example: false
267
268
      responses:
        '200':
269
          description: Search results
270
271
272
          content:
            application/json:
              schema:
273
                $ref: '#/components/schemas/SearchResult'
274
275
276
277
278
        default:
          description: unexpected error
          content:
            application/json:
              schema:
279
                $ref: '#/components/schemas/Error'
280
281
    post:
      summary: Create an object of specific type
282
      operationId: createObject
283
284
285
      tags:
        - objects
      parameters:
286
        - $ref: '#/components/parameters/type'
287
288
289
290
      requestBody:
        content:
          application/json:
            schema:
291
              title: ObjectCreationRequest
292
              type: object
293
294
295
296
              properties:
                attrs:
                  description: The attributes of the object to create, grouped by tab
                  type: object
297
298
299
300
301
                  example: {
                            "user": {
                              "givenName": "John",
                              "sn": "Smith"
                            },
302
303
                            "personalInfo": {
                              "personalTitle": "Dr"
304
305
                            }
                          }
306
307
308
                template:
                  description: The template to use to create the object
                  type: string
309
                  example: "cn=user-template,ou=templates,ou=people,dc=example,dc=com"
310
311
              required:
                - attrs
312
      responses:
313
        '201':
314
315
316
317
318
319
320
321
322
323
324
          description: DN of the created object
          content:
            application/json:
              schema:
                type: string
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
325
  '/objects/{type}/{dn}':
326
    get:
327
328
      summary: List tabs of the object, with name and status
      operationId: listObjectTabs
329
      tags:
330
        - objects
331
      parameters:
332
333
        - $ref: '#/components/parameters/type'
        - $ref: '#/components/parameters/dn'
334
335
      responses:
        '200':
336
          description: Tab list
337
338
339
          content:
            application/json:
              schema:
340
                title: TabStateList
341
342
                type: array
                items:
343
                  title: TabState
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
                  type: object
                  required: [class,name,active]
                  properties:
                    class:
                      type: string
                    name:
                      type: string
                    active:
                      type: boolean
                example: [
                            {
                              "class": "roleGeneric",
                              "name": "Role",
                              "active": true
                            },
                            {
                              "class": "applicationRights",
                              "name": "Applications",
                              "active": false
                            },
                            {
                              "class": "reference",
                              "name": "References",
                              "active": true
                            },
                            {
                              "class": "ldapDump",
                              "name": "LDAP",
                              "active": true
                            }
                          ]
375
376
377
378
379
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
380
                $ref: '#/components/schemas/Error'
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
    delete:
      summary: Delete the object
      operationId: deleteObject
      tags:
        - objects
      parameters:
        - $ref: '#/components/parameters/type'
        - $ref: '#/components/parameters/dn'
      responses:
        '204':
          description: success
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
398
399
400
401
402
403
404
405
406
407
408
409
410
411
    patch:
      summary: Set the object attributes
      operationId: modifyObject
      tags:
        - objects
      parameters:
        - $ref: '#/components/parameters/type'
        - $ref: '#/components/parameters/dn'
      requestBody:
        description: The new values for the attributes, grouped by tab
        content:
          application/json:
            schema:
              type: object
412
413
414
415
416
417
418
            example: {
                      "user": {
                        "givenName": "John",
                        "sn": "Smith"
                      },
                      "posixAccount": {
                        "homeDirectory": "/home/john"
419
                      }
420
                    }
421
      responses:
422
423
424
425
426
427
        '200':
          description: DN of the modified object
          content:
            application/json:
              schema:
                type: string
428
429
430
431
432
433
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
  '/objects/{type}/{dn}/templatefields':
    get:
      summary: List fields asked to use a specific template
      operationId: getTemplateFields
      tags:
        - objects
      parameters:
        - $ref: '#/components/parameters/type'
        - $ref: '#/components/parameters/dn'
      responses:
        '200':
          description: Attribute list grouped by tab
          content:
            application/json:
              schema:
                type: object
450
451
452
453
454
455
456
457
              example: {
                        "user": [
                          "sn",
                          "givenName",
                          "base",
                          "uid"
                        ]
                      }
458
459
460
461
462
463
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
464
  '/objects/{type}/{dn}/{tab}':
465
466
    get:
      summary: Get attributes values from object specific tab
467
      operationId: getObjectTab
468
      tags:
469
        - attributes
470
      parameters:
471
472
473
        - $ref: '#/components/parameters/type'
        - $ref: '#/components/parameters/dn'
        - $ref: '#/components/parameters/tab'
474
475
      responses:
        '200':
476
          description: Attribute values
477
478
479
480
481
482
483
484
485
          content:
            application/json:
              schema:
                type: object
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
486
                $ref: '#/components/schemas/Error'
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
    patch:
      summary: Set the object attributes of a specific tab
      operationId: modifyObjectTab
      tags:
        - objects
      parameters:
        - $ref: '#/components/parameters/type'
        - $ref: '#/components/parameters/dn'
        - $ref: '#/components/parameters/tab'
      requestBody:
        description: The new values for the attributes
        content:
          application/json:
            schema:
              type: object
502
503
504
            example: {
                      "fdNickName": ["Jonny"]
                    }
505
      responses:
506
507
508
509
510
511
        '200':
          description: DN of the modified object
          content:
            application/json:
              schema:
                type: string
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Deactivate the tab
      operationId: disableTab
      tags:
        - objects
      parameters:
        - $ref: '#/components/parameters/type'
        - $ref: '#/components/parameters/dn'
        - $ref: '#/components/parameters/tab'
      responses:
        '204':
          description: success
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
536
  '/objects/{type}/{dn}/{tab}/{attribute}':
537
538
    get:
      summary: Get a single attribute value(s)
539
      operationId: getAttributeValues
540
      tags:
541
        - attributes
542
      parameters:
543
544
545
        - $ref: '#/components/parameters/type'
        - $ref: '#/components/parameters/dn'
        - $ref: '#/components/parameters/tab'
546
        - $ref: '#/components/parameters/attribute'
547
548
      responses:
        '200':
549
          description: The attribute value(s)
550
551
552
          content:
            application/json:
              schema:
553
                $ref: '#/components/schemas/AnyThing'
554
555
556
557
558
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
559
                $ref: '#/components/schemas/Error'
560
561
    put:
      summary: Set attribute value(s)
562
      operationId: setAttributeValues
563
      tags:
564
        - attributes
565
      parameters:
566
567
568
        - $ref: '#/components/parameters/type'
        - $ref: '#/components/parameters/dn'
        - $ref: '#/components/parameters/tab'
569
        - $ref: '#/components/parameters/attribute'
570
571
572
573
574
575
      requestBody:
        description: The new value(s)
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnyThing'
576
            example: ["jsmith@example.com"]
577
      responses:
578
579
580
581
582
583
        '200':
          description: DN of the modified object
          content:
            application/json:
              schema:
                type: string
584
585
586
587
588
589
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
590
591
592
593
594
595
596
597
598
599
600
601
    delete:
      summary: Reset the attribute to its default value
      operationId: resetAttributeValue
      tags:
        - attributes
      parameters:
        - $ref: '#/components/parameters/type'
        - $ref: '#/components/parameters/dn'
        - $ref: '#/components/parameters/tab'
        - $ref: '#/components/parameters/attribute'
      responses:
        '200':
602
          description: The attribute new value(s)
603
604
605
606
607
608
609
610
611
612
613
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnyThing'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  '/objects/{type}/{dn}/{tab}/{attribute}/values':
614
    patch:
615
      summary: Add attribute values. Only on multivaluated attributes.
616
      operationId: addAttributeValues
617
618
619
      tags:
        - multivaluated
      parameters:
620
621
622
        - $ref: '#/components/parameters/type'
        - $ref: '#/components/parameters/dn'
        - $ref: '#/components/parameters/tab'
623
        - $ref: '#/components/parameters/attribute'
624
625
626
627
628
629
630
631
      requestBody:
        description: The values to add
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AnyThing'
632
            example: ['jsmith2@example.com']
633
      responses:
634
635
636
637
638
639
        '200':
          description: DN of the modified object
          content:
            application/json:
              schema:
                type: string
640
641
642
643
644
645
646
647
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete attribute values. Only on multivaluated attributes.
648
      operationId: deleteAttributeValues
649
650
651
      tags:
        - multivaluated
      parameters:
652
653
654
        - $ref: '#/components/parameters/type'
        - $ref: '#/components/parameters/dn'
        - $ref: '#/components/parameters/tab'
655
        - $ref: '#/components/parameters/attribute'
656
657
658
659
660
661
662
663
      requestBody:
        description: The values to remove
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AnyThing'
664
            example: ['jsmith2@example.com']
665
      responses:
666
        '204':
667
668
669
670
671
672
673
          description: success
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
  '/userlock/{dn}':
    get:
      summary: Get lock state of a user
      operationId: getLockState
      tags:
        - objects
      parameters:
        - $ref: '#/components/parameters/dn'
      responses:
        '200':
          description: Whether the user is locked
          content:
            application/json:
              schema:
                type: boolean
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Set lock state of a user
      operationId: setLockState
      tags:
        - objects
      parameters:
        - $ref: '#/components/parameters/dn'
      requestBody:
        description: Whether to lock or unlock the user
        content:
          application/json:
            schema:
              type: boolean
708
            example: true
709
710
711
712
713
714
715
716
717
      responses:
        '204':
          description: Success
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
718
719
720
721
722
723
724
725
726
727
728
729
730
  '/recovery':
    get:
      summary: Generate recovery token for a user
      operationId: getRecoveryToken
      tags:
        - recovery
      parameters:
        - name: email
          in: query
          required: true
          description: The email address of the user
          schema:
            type: string
731
          example: "email@example.com"
732
733
      responses:
        '200':
734
          description: Token and login
735
736
737
          content:
            application/json:
              schema:
738
                title: RecoveryResponse
739
740
741
742
743
744
                type: object
                properties:
                  token:
                    description: Recovery token
                    type: string
                    example: "opaquetokenstring"
745
746
                  login:
                    description: The login of the user
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
                    type: string
                    example: "fd-admin"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Change a user password using a recovery token
      operationId: confirmRecoveryPasswordChange
      tags:
        - recovery
      requestBody:
        description: User information
        content:
          application/json:
            schema:
765
              title: RecoveryRequest
766
767
768
769
770
771
              type: object
              properties:
                token:
                  description: Recovery token
                  type: string
                  example: "opaquetokenstring"
772
773
                login:
                  description: The login of the user
774
775
776
777
778
779
780
781
782
783
784
                  type: string
                  example: "fd-admin"
                password1:
                  description: First password entered by the user
                  type: string
                  example: "newpassword"
                password2:
                  description: Second password entered by the user
                  type: string
                  example: "newpassword"
              required:
785
                - login
786
787
788
789
790
791
792
793
794
795
796
797
                - password1
                - password2
                - token
      responses:
        '204':
          description: Success
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
798
799
components:
  schemas:
800
801
802
803
804
805
806
    AnyThing:
      anyOf:
        - type: string
        - type: array
          items:
            $ref: '#/components/schemas/AnyThing'
        - type: object
807
808
    Object:
      type: object
809
      additionalProperties:
810
        anyOf:
811
812
813
814
815
816
817
818
          - type: string
          - type: array
            items:
              type: string
          - type: object
    SearchResult:
      type: object
      additionalProperties:
819
        anyOf:
820
821
822
823
          - type: string
          - type: array
            items:
              type: string
824
825
826
827
828
    Type:
      type: object
      properties:
        name:
          type: string
829
          example: "Role"
830
831
        description:
          type: string
832
          example: "Organizational role"
833
834
        mainAttr:
          type: string
835
          example: "cn"
836
837
        nameAttr:
          type: string
838
          example: "cn"
839
840
        icon:
          type: string
841
          example: "geticon.php?context=types&icon=role&size=16"
842
843
        ou:
          type: string
844
          example: "ou=roles,"
845
846
        mainTab:
          type: string
847
          example: "roleGeneric"
848
849
850
851
852
853
        templateActive:
          type: boolean
        snapshotActive:
          type: boolean
        aclCategory:
          type: string
854
          example: "role"
855
856
        filter:
          type: string
857
          example: "(&(objectClass=organizationalRole)(!(objectClass=simpleSecurityObject)))"
858
859
        management:
          type: string
860
          example: "groupManagement"
861
862
        filterRDN:
          type: string
863
          example: "(ou:dn:=roles)"
864
865
866
        tabs:
          type: array
          items:
867
            $ref: '#/components/schemas/TabDef'
868
          example: [{
869
870
                      "class": "roleGeneric",
                      "name": "Role"
871
872
                    },
                    {
873
874
                      "class": "applicationRights",
                      "name": "Applications"
875
876
877
878
879
880
                    }]
    TypeList:
      type: object
      additionalProperties:
        type: string
      example: {"CONFIGURATION":"FusionDirectory configuration","DASHBOARD":"Dashboard","OGROUP":"Group","SPECIAL":"special","ROLE":"Role","USER":"User","LOCALITY":"Locality","DEPARTMENT":"Department","DCOBJECT":"Domain Component","COUNTRY":"Country","ACLROLE":"ACL role","ACLASSIGNMENT":"ACL assignment","ORGANIZATION":"Organization","DOMAIN":"Domain"}
881
    TabDef:
882
      type: object
883
      required: [class,name]
884
      properties:
885
        class:
886
          type: string
887
        name:
888
          type: string
889
890
891
892
893
894
895
896
897
898
    TabInfo:
      type: object
      properties:
        sections:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/SectionInfo'
        sections_order:
          type: array
          example: ["main","members"]
899
          items:
900
901
902
903
            type: string
    SectionInfo:
      type: object
      properties:
904
        name:
905
906
907
908
909
910
911
          type: string
          example: "Information"
        attrs:
          type: array
          example: ["base","cn","description","telephoneNumber","facsimileTelephoneNumber"]
          items:
            type: string
912
913
914
915
916
917
918
919
920
    Error:
      required:
        - message
      properties:
        message:
          type: string
  parameters:
    base:
      name: base
921
922
      example: "dc=example,dc=com"
      description: The LDAP base to use
923
924
925
926
927
      in: query
      schema:
        type: string
    filter:
      name: filter
928
929
      example: "(cn=a*)"
      description: An LDAP filter to search with
930
931
932
      in: query
      schema:
        type: string
933
934
935
936
937
938
939
940
941
942
943
    type:
      name: type
      in: path
      example: "user"
      required: true
      description: An object type
      schema:
        type: string
    dn:
      name: dn
      in: path
944
      example: "uid=jsmith,ou=people,dc=example,dc=com"
945
946
947
948
949
950
951
      required: true
      description: The dn of an existing object
      schema:
        type: string
    tab:
      name: tab
      in: path
952
      example: "personalInfo"
953
      required: true
954
      description: An existing tab class
955
956
      schema:
        type: string
957
958
959
    attribute:
      name: attribute
      in: path
960
      example: "fdPrivateMail"
961
962
963
964
      required: true
      description: The attribute
      schema:
        type: string
965
966
967
968
969
  securitySchemes:
    session:
      type: apiKey
      name: Session-Token
      in: header