feat(#10221): add documentation to create and update person, place and report #1962

apoorvapendse · 2025-08-18T12:38:01Z

Addresses: medic/cht-core#10221.

Description

WIP documentation updates to add POST /api/v1/person and PUT /api/v1/person endpoints
[description]

POST /api/v1/person

PUT /api/v1/person

License

The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.

sugat009

Cool! Can you add all the endpoints in this PR?

sugat009 · 2025-08-19T06:39:45Z

content/en/building/reference/api.md

 ```

+### POST /api/v1/person
+


issue: add a "added in X.X.X" version note for all the endpoints

sugat009 · 2025-08-19T06:41:43Z

content/en/building/reference/api.md

 ```

+### POST /api/v1/person
+


issue: add the description of the endpoint

sugat009 · 2025-08-19T06:44:02Z

content/en/building/reference/api.md

+Either of the two:
+1. `can_edit` 
+2. `can_view_contacts` and `can_create_people`


Suggested change

Either of the two:

1. `can_edit`

2. `can_view_contacts` and `can_create_people`

Should have `can_edit` or both `can_view_contacts` and `can_create_people`

The wording seemed a bit confusing to me.

sugat009 · 2025-08-19T06:47:19Z

content/en/building/reference/api.md

+| Key  | Description                         |
+| ---- | ----------------------------------- |
+| name | String used to describe the person. |
+| type | ID of the `contact_type` for the new person. Pass in `person` for older versions. |
+| parent | ID of the parent document, which is a place, for the new person. The type of the parent must belong to one of the allowed `parents` for the `contact_type` id in the settings config. |
+
+#### Optional
+
+| Key           | Description                                                            |
+| ------------- | ---------------------------------------------------------------------- |
+| reported_date | Timestamp of when the record was reported or created. Defaults to now. |
+| _id | ID of the new person document to be created. |
+| short_name | String to denote short name of the person. |
+| phone | Phone number of the person in string format. |
+| role | Role of the person in string format. |


suggestion: let's use fields instead of key here

sugat009 · 2025-08-19T06:48:31Z

content/en/building/reference/api.md

+#### Required
+| Key  | Description                         |
+| ---- | ----------------------------------- |
+| name | String used to describe the person. |


sugat009 · 2025-08-19T06:49:00Z

content/en/building/reference/api.md

+| Key           | Description                                                            |
+| ------------- | ---------------------------------------------------------------------- |
+| reported_date | Timestamp of when the record was reported or created. Defaults to now. |
+| _id | ID of the new person document to be created. |


suggestion: how about adding another column that contains the type of the field instead of doing a "... string format" in the description?

Hmm makes sense.

sugat009 · 2025-08-19T06:52:49Z

content/en/building/reference/api.md

+    "contact_type": "person"
+}
+```
+### PUT /api/v1/person


Suggested change

### PUT /api/v1/person

### PUT /api/v1/person

sugat009 · 2025-08-19T06:54:08Z

content/en/building/reference/api.md

+| reported_date | Timestamp of when the record was reported or created. |
+| contact_type| Required if the type of the person is `contact`. |
+| type | The type of the person. |
+| parent | The parent lineage of the person to be updated, can be hydrated or dehydrated. |


issue: parent cannot be updated

I think it would be helpful to document why parent cannot be updated

I meant "person to be updated"'s parent

ohhh, my bad. I misread this.

Signed-off-by: apoorvapendse <[email protected]>

Signed-off-by: Apoorva Pendse <[email protected]>

Signed-off-by: apoorvapendse <[email protected]>

sugat009 · 2025-08-25T04:20:55Z

content/en/building/reference/api.md


+### POST /api/v1/person
+
+*Added in x.x.x*


issue: not literally x.x.x. It indicates the CHT version in which the API was released.

For now you can add the version as 5.0.0. If something changes, it can be changed.

sugat009 · 2025-08-25T04:36:25Z

content/en/building/reference/api.md

+#### Permissions
+Either of the two:
+1. `can_edit` 
+2. `can_view_contacts` and `can_update_people`


issue: make the same changes as above in this section as well

sugat009 · 2025-08-25T04:36:59Z

content/en/building/reference/api.md

+| parent | The parent lineage of the place to be updated. Not required if the place is at the top of the hierarchy. | Minified or hydrated parent lineage |
+| contact | The contact lineage linked with the place. This can be inserted as a part of update if not already present. | Minified or hydrated  lineage |
+
+### Required mutable fields


Suggested change

### Required mutable fields

#### Required mutable fields

content/en/building/reference/api.md

sugat009 · 2025-08-25T04:57:20Z

content/en/building/reference/api.md

+| Field  | Description                         | Format |
+| ---- | ----------------------------------- | -------- |
+| name | Name of the person. | string |
+| type | ID of the `contact_type` for the new person. Pass in `person` for older versions. | string |
+| parent | ID of the parent document, which is a place, for the new person. The type of the parent must belong to one of the allowed `parents` for the `contact_type` id in the settings config. | UUID string |


suggestion: if there is an option to format these tables in your editor, then please do so. For reference check the GET API's table.

Co-authored-by: Sugat Bajracharya <[email protected]>

Signed-off-by: Apoorva Pendse <[email protected]>

sugat009

LGTM!
I'll merge this once the release version for medic/cht-core#9835 is finalized.

content/en/building/reference/api.md

Signed-off-by: Apoorva Pendse <[email protected]>

apoorvapendse · 2025-11-05T13:37:29Z

Updates: (similar for person and report endpoints)

Signed-off-by: Apoorva Pendse <[email protected]>

apoorvapendse marked this pull request as draft August 18, 2025 12:38

apoorvapendse force-pushed the create-update-person-docs branch from de913a3 to 77fca3c Compare August 18, 2025 12:39

sugat009 self-requested a review August 19, 2025 06:33

sugat009 assigned apoorvapendse Aug 19, 2025

sugat009 added the Type: Feature Add something new label Aug 19, 2025

sugat009 marked this pull request as ready for review August 19, 2025 06:34

sugat009 requested changes Aug 19, 2025

View reviewed changes

feat(#10221): add documentation to create/update a person

01752bd

Signed-off-by: apoorvapendse <[email protected]>

apoorvapendse force-pushed the create-update-person-docs branch from 77fca3c to 01752bd Compare August 19, 2025 13:51

create place documentation

e57d4bc

Signed-off-by: Apoorva Pendse <[email protected]>

apoorvapendse force-pushed the create-update-person-docs branch 2 times, most recently from 3bdce51 to f5429a0 Compare August 19, 2025 14:56

update place documentation

ab7235b

Signed-off-by: apoorvapendse <[email protected]>

apoorvapendse force-pushed the create-update-person-docs branch from f5429a0 to ab7235b Compare August 19, 2025 14:56

report create/update documentation

c8906e4

Signed-off-by: apoorvapendse <[email protected]>

sugat009 self-requested a review August 25, 2025 04:19

sugat009 requested changes Aug 25, 2025

View reviewed changes

apoorvapendse and others added 2 commits August 25, 2025 11:59

Update content/en/building/reference/api.md

79e86a9

Co-authored-by: Sugat Bajracharya <[email protected]>

formatting and other minor fixes

0bf3846

Signed-off-by: Apoorva Pendse <[email protected]>

apoorvapendse requested a review from sugat009 August 25, 2025 06:53

sugat009 approved these changes Aug 25, 2025

View reviewed changes

sugat009 requested changes Aug 27, 2025

View reviewed changes

sugat009 added 8 commits August 27, 2025 12:57

Update content/en/building/reference/api.md

038ff2b

Update content/en/building/reference/api.md

2c9daeb

Update content/en/building/reference/api.md

faedfbb

Update content/en/building/reference/api.md

5afbe37

Update content/en/building/reference/api.md

e6cbd84

Update content/en/building/reference/api.md

4ed2c52

Update content/en/building/reference/api.md

32a9940

Update content/en/building/reference/api.md

7507de7

sugat009 added 4 commits August 27, 2025 13:07

Update content/en/building/reference/api.md

102e8cc

Update content/en/building/reference/api.md

da1180e

Update content/en/building/reference/api.md

cc38e87

Update content/en/building/reference/api.md

ac01556

sugat009 changed the title ~~feat(#10221): add documentation to create/update a person~~ feat(#10221): add documentation to create and update person, place and report Aug 28, 2025

andrablaj removed the Type: Feature Add something new label Sep 23, 2025

use the :uuid route param for updates

ea56a31

Signed-off-by: Apoorva Pendse <[email protected]>

change release version to 5.1.0 from 5.0.0

b152e28

Signed-off-by: Apoorva Pendse <[email protected]>

sugat009 approved these changes Nov 6, 2025

View reviewed changes

	\| name \| String used to describe the person. \|
	\| name \| Name of the person. \|

	\| _id \| ID of the new person document to be created. \|
	\| _id \| ID of the new person document to be created in UUID format. \|

feat(#10221): add documentation to create and update person, place and report #1962

Are you sure you want to change the base?

feat(#10221): add documentation to create and update person, place and report #1962

Uh oh!

Conversation

apoorvapendse commented Aug 18, 2025

Description

License

Uh oh!

sugat009 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sugat009 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

apoorvapendse commented Nov 5, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants