Make the documentation of the API more complete

[mpelley]

Some items that are missing:

• The type of authentication to use. Basic? Bearer token? Other?
• The strings to use for the various types of entities.
• The ID to use for the various types of entities. I assume I can use the displayed number for the ID of a test case. What do I use for the ID of a project?
• Some examples that reference the demo project entities.

For example, I thought this (with basic authentication) would return a list of test cases in the Quack UI demo project: localhost/api/quackui/testcases but it returned "404 Not found".

[azee]

Hi Mike,

Thank you, will prioritize it.

API authentication is done via a single header "Whoru-Api-Token" https://github.com/greatbit/whoru/blob/master/auth/src/main/java/ru/greatbit/whoru/auth/utils/HttpUtils.java#L12

Every user has this value generated and it can be obtained from the DB. But usually a global admin token is specified in property files https://github.com/greatbit/quack/blob/master/api/src/main/resources/quack.properties#L21

When passed as a Whoru-Api-Token - the request will be authenticated.

Currently we are working on cloud solution that will have standard OATH/JWT-based methods.

[azee]

Till documentation is not ready, here is a tip All api calls are basing from projectID and have similar structure

localhost/api/{PROJECT_ID}/{ENTITY_TYPE}

In your case project id is quackui

All entities - testcases, testsuites, launches, attributes - all follow the same CRUD pattern

@get localhost/api/{PROJECT_ID}/{ENTITY_TYPE}/{ID} - get one entity @post/put localhost/api/{PROJECT_ID}/{ENTITY_TYPE}/ - body = entityJSON - update or create - depends on if ID field exists @delete localhost/api/{PROJECT_ID}/{ENTITY_TYPE}/{ID} - delete entity @get localhost/api/{PROJECT_ID}/{ENTITY_TYPE} - get all available entities

@get localhost/api/{PROJECT_ID}/{ENTITY_TYPE} + ?queryParameters - filter entites. Any entity fields can be used as query parameters. E.g., if you want to filter testcases with title "AAA" or "BBB" and id="1" or id="2", you will do localhost/api/quackui/testcases?title=AAA&title=BBB&id=1&id=2 This will work with all fields of entities, even embedded. E.g., you can filter by attributes like ?attribute={ATTR_ID}.{ATTRVALUE} For numbers you can use specific prefixes from and to E.g., if you want to filter for testcases created between specific time range, you can do localhost/api/quackui/testcases?from createdTime=123&to_ createdTime=345

[mpelley]

I am interested in self-hosting the open-source version of Quack, not the cloud solution. I would like to populate Quack from our existing test management system via the API. I'm not familiar enough with MongoDb to go directly to it. I hope that going through the API will ensure the database gets set up the way Quack likes to see it.

I got the Whoru-Api-Token to work, so I can start using the API. But I tried to change the "abc" to "abcdefgh" in quack.properties and Quack still accepts "abc" and not "abcdefgh". I tried shutting down and restarting the server with no change. What do I need to do to get the change in properties to be used?

Also, how do I create a new project through the API?

[azee]

@mpelley The easiest way to see how API works - just do the action in UI and see what is being sent to the backend. UI uses the very same API - it just uses cookies for authentication instead of tokens.

To create a project you send a POST request to /api/project with a project body {allowedGroups: [],description: "Descr", id: "sometesthere",name: "SomeTestHere"}

ID will be used in all URLs to all project resources. So I recommend keeping it meaningful.

[azee]

Properties should work though. Where do you update properties - is it in resources folder or located separately on your machine? If in resources - make sure to re-build the project before you restart. If it is a separate file - makes sure you specify it's location as a boot classpath if you are running a JAR/WAR file like -Xbootclasspath/a:/PATH_TO_PROPERTIES_FOLDER/ Or map the docker property folder to where you keep your local configs in case you are using docker: docker run -v PATH_TO_DIRECTORY_WITH_PROPERTIES:/etc/quack

[azee]

@mpelley I believe I'll be able to provide feedback much faster if you contact me directly via linkedin https://www.linkedin.com/in/anamazov