Operations review #3
Conversation
| They are: | ||
|
|
||
| - `page`, an integer specifying the page being fetched | ||
| - `size`, an integer specifying the size of the page |
There was a problem hiding this comment.
Add something about sorting the results. Or maybe say that we return a spring Page[1]
[1] https://docs.spring.io/spring-data/rest/docs/2.0.0.M1/reference/html/paging-chapter.html
| Here we list all the available endpoints from this microservice. For easily testing this microservice, we recomend to see our [postman collection](https://github.com/Leaf-Agriculture/postman-collections). | ||
|
|
||
| Here we list all the available endpoints from this microservice. For easily | ||
| testing it, we recomend to see our Postman [collection][1]. |
There was a problem hiding this comment.
Did you mean to drop the link to the postman collection?
There was a problem hiding this comment.
No no. This is just a way to reference the link by a number. The links are located in the end of the file.
| check the status of the return object for modifications. | ||
|
|
||
| A merge process has some limitations however. The files passed must belong to | ||
| the same user, be of the same operation type and have the status as `CONVERTED`. |
There was a problem hiding this comment.
The status of files is not explained in the relevant section, but the user needs to know what it means for a file to have the 'CONVERTED' status. I think we should either add a similar explanation to the section on POST /files to explain how the file will progress through the statuses and what they mean. Or, we could simply explain right here that a file becomes converted if ___ is true and after ___ is complete.
We also should state how often the auto-merge is expected to take place. Knowing it's async, the user might still expect it to be available after just minutes. Lastly, we enumerate the status values in the POST /files section, but here we should specifically state that a merge file is ready for the user when the status is _____.
There are some minor wording suggestions I have as well. So here's a copy with some changes. Also note the type on 'request':
A merge operation is performed asynchronously each night. This call will return immediately with the newly created file entry, but at this point the file is not already processed and available. You will need to make new GET /files request for the new id and check the status. A status value of ____ means the file is done merging.
There was a problem hiding this comment.
I was thinking that these kind of "guides" should be placed in another section. This section is just the reference for the API. But I agree that there are lots of concepts that we use, and reference in here, that should be explained.
There was a problem hiding this comment.
I've have updated the section. However, I have not added further explanations in the guide. Maybe create another section? I am open to discuss it.
No description provided.