Open APIs

Expand all | Collapse all

404 or 204 or 200 with empty response

  • 1.  404 or 204 or 200 with empty response

    TM Forum Member
    Posted Apr 08, 2021 06:32
    Hi all,

    When an URI does not have any results satisfying the specified filters, what should be the response? For example what should be the response of the below URIs

    1. prepayBalanceManagement/v4/adjustBalance/invalidID
    2. prepayBalanceManagement/v4/adjustBalance?id=invalidID
    3. prepayBalanceManagement/v4/adjustBalance?id=valid&partyAccount.id=invalidID
    4. prepayBalanceManagement/v4/adjustBalance?partyAccount.id=invalidID (For ex, no adjustBalance created on the account given)

    For the first case, spec clearly mentions that 404 would be the appropriate response.
    However, I wanted to confirm for other cases as well since I did not  find any explicit mention of the expectation and this would impact all our implementations.

    Thanks in advance,
    Sravya

    ------------------------------
    Sravya A
    Oracle Corporation
    ------------------------------


  • 2.  RE: 404 or 204 or 200 with empty response

    TM Forum Member
    Posted Apr 08, 2021 07:16
    According to the design guidelines (TMF630 Part 1 section 4), also GET with filter should return 404 if no matching entities are found.
    Hope it helps

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------



  • 3.  RE: 404 or 204 or 200 with empty response

    TM Forum Member
    Posted Apr 14, 2021 05:12
    Hello Jonathan,

    Stated section in TMF630 clearly mentions 404 error for a single resource query .i.e <uri path>/<ID>
    For other scenarios however, there is no explicit mention on what the response should be if there are no records matching the filters. This looks ambiguous. Since I got varied responses here too, I am unable to reach to a conclusion. Is there a way to get this clarified and document the samples in TMF630 or in API conformance docs/CTK scenarios?

    ------------------------------
    Sravya A
    Oracle Corporation
    ------------------------------



  • 4.  RE: 404 or 204 or 200 with empty response

    TM Forum Member
    Posted Apr 09, 2021 01:09
    On Apr 08, 2021 06:32 @Sravya A wrote:​​
    > When an URI does not have any results satisfying the specified filters, what should be the response?

    Yes, the first case is a retrieval of an item, identified by id, in the adjustBalance Collection, if it doesn't exist 404 is the correct response.

    The rest of the examples are queries on the adjustBalance Collection. If the client provided a query with incorrect syntax expect a 400 response.  If the server experiences an internal error expect a 500 response. Otherwise the query is "successful" and the success result body is an array of items in the Collection matching the query filters.  If no items match expect an empty array ("[]") in the body with a 200 OK response.


    ------------------------------
    Vance Shipley
    SigScale
    ------------------------------



  • 5.  RE: 404 or 204 or 200 with empty response

    TM Forum Member
    Posted Apr 14, 2021 05:22
    We've taken it internally in the Open API team, with intent to update the design guidelines to ensure that any ambiguity is removed. It is looking like we'll go for what Vance stated here (200 for no matching result), but let's wait until the update is made and approved.

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------



  • 6.  RE: 404 or 204 or 200 with empty response

    TM Forum Member
    Posted Jul 20, 2021 04:00

    Hey Folks,

    I have a supplemental question:

    What would be the correct response for a GET on an empty collection? E.g. GET prepayBalanceManagement/v4/adjustBalance/

    I would expect a respond with status 200 and x-total-count=0, x-result-count=0

    Couldn't find anything within the Guidelines which defines the behaviour.


    Cheers,

    Jan



    ------------------------------
    Jan Lemmermann
    OSS Lead Architect
    EWE TEL GmbH
    ------------------------------



  • 7.  RE: 404 or 204 or 200 with empty response

    TM Forum Member
    Posted Jul 21, 2021 10:08
    This seems to be the proper way to go as it is compliant with the general industry consensus on RESTfull API behavior.

    p.s. The question is completely generic to RESTful APIs and not TMF or even telco industry specific. I've got into the Telco industry just recently and started looking at the TMF APIs... and it feels a little that it tries to reinvent the wheel sometimes. I believe that there are plenty of well defined general guidelines for RESTfull API design already (e.g. https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md) that TMF could build upon instead of reinventing it's own. This might leave more resources to focus on the industry specific aspects (at the higher logical modeling level). Reusing common "protocol level" principles would also make the entry into the Telco industry somewhat easier for the engineering talent that is already fully comfortable building and consuming APIs in those other industries.

    ------------------------------
    Justas Vilimas
    Telia Company
    ------------------------------