api Convo - nonduality345/Convos GitHub Wiki

/api/Convo

  • GET

    When performing the GET method on this endpoint, the application returns a list of all Convos where the user is either the creator or the participant. By default, the endpoint, as is, will return the first page of 10 Convos for the user. Paging is facilitated using the paging methodology described here.

    • Request

      • Custom Headers
        • X-Authorization: {userId} Required
      • Body

        None

    • Response

      • Custom Headers
        • X-Last-Modified

          This header holds the last Convo that was created before the date and time specified in the before query string parameter. If there is no before query string parameter, a default date and time of 9999-12-31T23:59:59 is considered. This value is important for cache invalidation. If a new Convo is created sooner than the last Convo that was created before the date and time specified in the before query string parameter, but still occurs before the before date and time, the contents of the response would change. Therefore, the cache should be invalidated.

        • X-Message

          In the case of 4xx responses from the API where the custom result code is > 0, this header will hold a message describing the client based error that occurred.

        • X-Response-Count

          This header will hold the number of Convos that were returned in the current request.

        • X-Result-Code:

          This header holds the custom result code of the operation. A successful response will return 0 (OK) to the client. Details of results codes can be found here.

        • X-Total-Count

          This header will hold the total number of Convos in the user's inbox (subject to the before query string parameter constraint).

        • X-URI-Next-Page

          This header holds the URI to the next set of Convos in the current paging scheme of the request. If the user requested a list of convos with the index_=_0, count_=_5 and before_=_9999-12-31T23:59:59, this header would have the URI to the next set of Convos where index_=_1, count_=_5 and before_=_9999-12-31T23:59:59, but only if there exists Convos in the next set. This header is excluded if there are no more Convos following the current set.

      • Body

      A list of Convo objects are returned, ordered by the date of the last message descending, followed by the date it was created descending.

      • Status

      A 200 (OK) status code is sent for successful requests. Requests with bad client information will return a 4xx level error and if there are problems with the server, a 5xx level status code is sent.

  • POST

    When performing a POST operation on this endpoint, a new Convo will be created in the system.

    • Request

      • Custom Headers
        • X-Authorization: {userId} Required
      • Body
        {
            "Participant":9999, 
            "Subject":"Subject of the Convo"
        }
        

        The body of a post request is an object with two fields. The "Participant" field is the user Id of the person who is also participating in this Convo (since each Convo is a conversation between two people). The "Subject" field contains the subject of the Convo. There is a maximum character limit of 140 characters on this field.

    • Response

      • Custom Headers
        • X-Message

          In the case of 4xx responses from the API where the custom result code is > 0, this header will hold a message describing the client based error that occurred.

        • X-Result-Code:

          This header holds the custom result code of the operation. A successful response will return 5 (CREATED) to the client. Details of results codes can be found here.

        • X-URI-Reference:

          This header holds the URI to the newly created resource.

      • Body

      None

      • Status

      A 201 (Created) status code is sent for successful requests. Requests with bad client information will return a 4xx level error and if there are problems with the server, a 5xx level status code is sent.