Monica: POST /contacts/ errors with undocumented required field "The is birthdate known field is required"

[jasonstrimpel]

Describe the bug
I create a POST request to the https://app.monicahq.com/api/contacts/ endpoint in an attempt to create a new contact. Following the documentation, I supply the example JSON payload and receive error code 32 for three fields that do not appear in the documentation.

The error response:

{
    "error": {
        "message": [
            "The is birthdate known field is required.",
            "The is deceased field is required.",
            "The is deceased date known field is required."
        ],
        "error_code": 32
    }
}

Screenshots

Which version are you using:

• Hosting version on https://app.monicahq.com

Additional context
By updating is_dead to is_deceased I was able to resolve the The is deceased field is required. error. I could not figure out any of the other fields.

[shavs]

I can confirm that this an issue with the documentation - the fields that are missing are:

| Property | Replaces? | Appears in JSON Response |
|---|---|---|
| is_deceased | is_dead | False - only is_dead appears |
| is_birthdate_known | none, added to response | False, behaviour seems to override birthdate_is_age_based, birthdate_is_year_unknown and birthdate_age in the request |
| is_deceased_date_known | none, added to response | I'm unsure of the side effects - I think it's overriding the deceased_date->is_year_unknown property, but I'm unsure. |

I am unsure whether this affects the self-hosted version of the site, however, I am making the assumption that both the hosted version at https://app.monicahq.com is the same version that can be self-hosted.

I'd see that either:

• the documentation needs to be changed, to fit the new properties on the request
• the API needs to be changed to fit the request, to be consistent with the response.

Here is the corrected JSON:

{
  "first_name": "henri",
  "last_name": "troyat",
  "nickname": "Rambo",
  "gender": "male",
  "birthdate": null,
  "is_birthdate_known": false,
  "birthdate_is_age_based": true,
  "birthdate_is_year_unknown": false,
  "birthdate_age": 29,
  "is_birthdate_approximate": "approximate",
  "age": 30,
  "job": "Animator",
  "company": "Star Wars",
  "food_preferencies": "Fish and fresh potatoes.",
  "first_met_information": "we met a bar.",
  "first_met_date": "1981-02-02",
  "first_met_date_is_age_based": false,
  "first_met_date_is_year_unknown": false,
  "first_met_date_age": null,
  "first_met_through_contact_id": 2,
  "is_partial": 0,
  "is_deceased": 1,
  "is_deceased_date_known": false,
  "deceased_date": "2017-02-02",
  "deceased_date_is_age_based": false,
  "deceased_date_is_year_unknown": true,
  "deceased_date_age": null,
  "avatar_url": "https://scontent-yyz1-1.xx.fbcdn.net/v/t1.0-1/p160x160/23561695_738743569647668_3975953680386408_n.jpg?oh=c32aa5f5c6c8d2ca927cbd2fcaa3&oe=5AA2632F"
}

[shavs]

Also, as a general rule-of-thumb - with Laravel or Lumen response validation messages, you can generally translate the validation messages into underscored properties. For example:

{
    "error": {
        "error_code": 32,
        "message": [
            "The is birthdate known field is required.",
            "The is deceased field is required.",
            "The is deceased date known field is required."
        ]
    }
}

{
    "error": {
        "error_code": 32,
        "message": [
            "The is_birthdate_known field is required.",
            "The is_deceased field is required.",
            "The is_deceased_date_known field is required."
        ]
    }
}

... I agree it should not be necessary, but it may assist with debugging the API in future.

[asbiin]

Thanks @shavs for the fix, we will update the doc.

[asbiin]

Related to #2251

[mattdp]

Related: https://github.com/monicahq/monica/issues/2398. I believe solving this solves both issues.

[asbiin]

API doc has been updated.
See https://github.com/monicahq/marketing_site/pull/75