Web Interface (Swagger REST API)

Owned by Copy Page Tree
Last updated: Jun 01, 2021 by Brian MillerVersion comment

Overview

Swagger is an interactive documentation system that also allows you to conveniently try out & make REST API calls from the documentation page itself.   

To interact with it, open a web browser to port 9000 of the root of your Syndeia Cloud instance, ex: http://myhost.mydomain.com:9000, login, click on "?", then API ("REST API Swagger Documentation"):  

 


The Swagger REST API Documentation page should open as shown below. The REST endpoints are organized based on a system of repositories, containers, artifacts, and relations (see Conceptual Model for an overview).

To Login

The sign-in request authenticates the user and returns a token if succesful. The token is then used for every REST API request to the Syndeia Cloud server. Follow the steps below to sign-in and register the token so that you do not have to specify it for each request. 

1.  Click on POST /signIn button under the Auth category.

2.  Click the Try it out button (RHS). The "User info for signIn" fields should show up.   

3.  Click the Edit button.  The field should now become editable.  

4.  Fill out your account credentials.
    

​5.  Click the blue Execute button.  

6.  If successful, you should receive an HTTP 200 response back with JSON data.  If there was a form error, you should receive an HTTP 4XX response back with an appropriate error message.  

7.  Select and copy the token JSON string into the clipboard
    

8.  Click the Authorize button at the top of the page (RHS)​, a popup screen should show.  
    
9.  Paste the copied token (previous step) in the Value field, and then click the Authorize button, followed by clicking the Done button.
   

To Create a New User

10.  Click on POST /signUp button, 

11.  Click the Try it out button.  The "User info for signUp" fields should show up.  
     ​

12.  Click the Edit button.  The field should now become editable.  

13.  Fill out the requested fields, ie: first name, last name, email, password.  

14.  Click the blue Execute button.  

15.  If successful, you should receive an HTTP 200 response back with JSON data.  If there was a form error, you should receive an HTTP 4XX response back with an appropriate error message.  

To Reset a Password

16.  Click on POST /resetpassword button, 

17.  Click the Try it out button.  The "User info for password reset" fields should show up.  
     ​

18.  Click the Edit button.  The field should now become editable.  

19.  Fill out the requested fields, ie: email, newPassword.  

20.  Click the blue Execute button.  

21.  If successful, you should receive an HTTP 200 response back with JSON data.  If there was a form error, you should receive an HTTP 4XX response back with an appropriate error message.  


(info) Note, Reset Password is considered an admin-level operation that requires the USER_MODIFY permission.  This is distinct from the Change Password operation which does not require any permission and only applies to one's own password.  

To Update a User (Permissions)

22.  Click on GET /api/v1/users/email/{email}
23.  Click the Try it out button.  The "User info that needs to be updated" fields should show up.  
     
24.  Fill out the requested field, ie: email.    

25.  Click the blue Execute button.  

26.  If successful, you should receive an HTTP 200 response back with JSON data.  If there was a form error, you should receive an HTTP 4XX response back with an appropriate error message.

27.  Copy the key value
      
28.  Click on PUT /api/v1/users/{key} button, 

29.  Click the Try it out button.  The "Get user" fields should show up.  
     

30.  Click the Edit button.  The field should now become editable.  

31.  Fill out the requested fields, ie: key, firstName, lastName, permissions.    

       (info)Currently the following permissions are available:

USER_CREATE

Create user permission

USER_READ

User read permission

USER_MODIFY

User modification permission

USER_REMOVE

User remove permission

REPOSITORY_CREATE

Create repository permission

REPOSITORY_MODIFY

Repository modification permission

REPOSITORY_DELETE

Repository deletion permission

CONTAINER_CREATE

Create container permission

CONTAINER_MODIFY

Container modification permission

ARTIFACT_RELATION_WRITE

Artifact relation write permission

CONTAINER_DELETE

Container deletion permission

READ

General read permission

32.  Click the blue Execute button.  

33.  If successful, you should receive an HTTP 200 response back with JSON data.  If there was a form error, you should receive an HTTP 4XX response back with an appropriate error message.

To Delete a User

34.  Click on GET /api/v1/users/email/{email}
35.  Click the Try it out button.  The "User info that needs to be updated" fields should show up.  
     
36.  Fill out the requested field, ie: email.    

37.  Click the blue Execute button.  

38.  If successful, you should receive an HTTP 200 response back with JSON data.  If there was a form error, you should receive an HTTP 4XX response back with an appropriate error message.

39.  Copy the key value
      
40.  Click on DELETE /api/v1/users/{key} button, 

41.  Click the Try it out button.  The "Delete a user given the user key" field should show up.  
     

42.  Fill out the requested field, ie: key.   

43.  Click the blue Execute button.  

44.  If successful, you should receive an HTTP 200 response back with JSON data.  If there was a form error, you should receive an HTTP 4XX response back with an appropriate error message.