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 and click on the API ("REST API Swagger Documentation") button:

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.

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.

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.

Syndeia 3.2

Web Interface (Swagger REST API)