docs: Migrated the stages component from the old docs to the new docs #253
Conversation
shinde-rahul
left a comment
shinde-rahul
left a comment
There was a problem hiding this comment.
@OfficialJhimmy, A minor touch-up and we are good to go.
- Fix double periods in parameter descriptions.
Please check the vale errors too.
adiati98
requested review from
adiati98 and
favour-chibueze
and removed request for
a team
…on-new into feyijimi-wth-new-stages
There was a problem hiding this comment.
@mautic/core-team I have a couple of questions here and left comments of things that I've changed. Basically, I'm trying to make this clearer and readable. Other than these, I changed all active to passive voices.
Once you review the content in this PR, and if you all agree with the changes, I'll apply them to all API sections in this docs.
Here's the live preview link: https://mautic-developer--253.org.readthedocs.build/en/253/rest_api/stages.html
And here's the original version as comparison: https://github.com/mautic/developer-documentation/blob/main/source/includes/_api_endpoint_stages.md
TIA! ✨
| - Stage ID | ||
| * - ``isPublished`` | ||
| - boolean | ||
| - Stage publication status |
There was a problem hiding this comment.
questions:
-
The
isPublishedtype here is boolean. However, in the JSON code example taken from this page, it's 1, which is integer (or number?). Which one is correct? -
Do we want to say
intor spell itinteger?
{
"stage": {
"id": 47,
"isPublished": 1,
"dateAdded": "2015-07-21T12:27:12-05:00",
"createdBy": 1,
"createdByUser": "Joe Smith",
"dateModified": "2015-07-21T14:12:03-05:00",
"modifiedBy": 1,
"modifiedByUser": "Joe Smith",
"name": "Stage A",
"category": null,
"description": "This is my first stage created via API.",
"weight": 0,
"publishUp": "2015-07-21T14:12:03-05:00",
"publishDown": "2015-07-21T14:12:03-05:00"
}
}
There was a problem hiding this comment.
We can change it to "isPublished": true as well. PHP doesn't mind. I wouldn't call it int because then someone can put 34534 in there. PHP will retype it to true but I think that everyone understands that 1=true and 0=false.
| .. code-block:: json | ||
|
|
||
| { | ||
| "stage": { | ||
| "id": 47, | ||
| "isPublished": 1, | ||
| "dateAdded": "2015-07-21T12:27:12-05:00", | ||
| "createdBy": 1, | ||
| "createdByUser": "Joe Smith", | ||
| "dateModified": "2015-07-21T14:12:03-05:00", | ||
| "modifiedBy": 1, | ||
| "modifiedByUser": "Joe Smith", | ||
| "name": "Stage A", | ||
| "category": null, | ||
| "description": "This is my first stage created via API.", | ||
| "weight": 0, | ||
| "publishUp": "2015-07-21T14:12:03-05:00", | ||
| "publishDown": "2015-07-21T14:12:03-05:00" | ||
| } | ||
| } |
There was a problem hiding this comment.
I've moved the JSON code example to the Response subsection for better navigation. That way, folks don't have to scroll up and down when they see "See JSON code example."
| Edit a Stage. This operation supports ``PUT`` or ``PATCH`` depending on the desired behavior: | ||
|
|
||
| * ``PUT``: creates a Stage when the ID doesn't exist. If the ID exists, the request clears the Stage data and adds the request values. | ||
| * ``PATCH``: updates field values for an existing Stage using the request data. The request fails when the ID doesn't exist. |
There was a problem hiding this comment.
The descriptions are moved from after code-block to right after title for clarity.
| Response | ||
| ======== | ||
|
|
||
| * ``PUT``: returns ``200`` when the request successfully edits a Stage or ``201`` when the request creates a Stage. | ||
| * ``PATCH``: returns ``200`` when the request successfully edits a Stage. |
There was a problem hiding this comment.
I added list to all responses and reword them for clarity. Please let me know if we'd like to roll back to the orginal version.
6 participants
No description provided.