Open APIs

 View Only
  • 1.  Use of HTTP Status 206 for pages

    TM Forum Member
    Posted Mar 10, 2021 01:56

    Sorry if I have a question about APIs again. We are trying to rely more on the TMF OpenAPIs and I realized that this is how questions come up with our developers.

    In the TMF OpenAPI Guidelines it is described that you should return the status code 206 Partial Content in case only a part of a resource collection is included in the body.
    Some of our developers noticed that 206 was not defined as a possible response in any of the Swagger files.

    I think it would make sense to include the status in the API specification then. No idea if I could support this change somehow. I would be happy to participate.

    Regards,

    Jan



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


  • 2.  RE: Use of HTTP Status 206 for pages

    TM Forum Member
    Posted Mar 10, 2021 03:15
    Edited by Jonathan Goldberg Mar 10, 2021 03:16
    Hi Jan
    I looked into this. To my understanding (see here and here), 206 is relevant only when a Range request was submitted. Range appears to be relevant when a request asks for byte or multi-part content, allowing the requestor to narrow down on parts of the request.
    This doesn't seem to be relevant for REST APIs in general, but perhaps I have misunderstood something.

    Hope it helps

    P.S. Please don't apologize for asking questions, that's what this community is for. There are no stupid questions, and many times these questions can lead to improvements in Open API design!

    ------------------------------
    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: Use of HTTP Status 206 for pages

    TM Forum Member
    Posted Mar 10, 2021 03:31

    Absolutely right. It's just unclear to me why the Swagger files don't mention the 206 status. It would make sense to describe aspects covered by the guidelines in the Swagger files as well. At least in the cases where Swagger allows a definition.

    An example is TMF675

    Current Swagger-File (excerpt):

    "paths": {
        "/geographicLocation": {
          "get": {
            "operationId": "listGeographicLocation",
            "summary": "List or find GeographicLocation objects",
            "description": "This operation list or find GeographicLocation entities",
            "tags": [
              "geographicLocation"
            ],
            "parameters": [
              {
                "name": "fields",
                "description": "Comma-separated properties to be provided in response",
                "required": false,
                "in": "query",
                "type": "string"
              },
              {
                "name": "offset",
                "description": "Requested index for start of resources to be provided in response",
                "required": false,
                "in": "query",
                "type": "integer"
              },
              {
                "name": "limit",
                "description": "Requested number of resources to be provided in response",
                "required": false,
                "in": "query",
                "type": "integer"
              }
            ],
            "responses": {
              "200": {
                "description": "Success",
                "headers": {
                  "X-Result-Count": {
                    "description": "Actual number of items returned in the response body",
                    "type": "integer"
                  },
                  "X-Total-Count": {
                    "description": "Total number of items matching criteria",
                    "type": "integer"
                  }
                },
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/definitions/GeographicLocation"
                  }
                }
              },
              "400": {
                "description": "Bad Request",
                "schema": {
                  "$ref": "#/definitions/Error"
                }
              },
              "401": {
                "description": "Unauthorized",
                "schema": {
                  "$ref": "#/definitions/Error"
                }
              },
              "403": {
                "description": "Forbidden",
                "schema": {
                  "$ref": "#/definitions/Error"
                }
              },
              "404": {
                "description": "Not Found",
                "schema": {
                  "$ref": "#/definitions/Error"
                }
              },
              "405": {
                "description": "Method Not allowed",
                "schema": {
                  "$ref": "#/definitions/Error"
                }
              },
              "409": {
                "description": "Conflict",
                "schema": {
                  "$ref": "#/definitions/Error"
                }
              },
              "500": {
                "description": "Internal Server Error",
                "schema": {
                  "$ref": "#/definitions/Error"
                }
              }
            }
          }



    My suggestion would be the following addition:

    "paths": {
        "/geographicLocation": {
          "get": {
            "operationId": "listGeographicLocation",
            "summary": "List or find GeographicLocation objects",
            "description": "This operation list or find GeographicLocation entities",
            "tags": [
              "geographicLocation"
            ],
            "parameters": [
              {
                "name": "fields",
                "description": "Comma-separated properties to be provided in response",
                "required": false,
                "in": "query",
                "type": "string"
              },
              {
                "name": "offset",
                "description": "Requested index for start of resources to be provided in response",
                "required": false,
                "in": "query",
                "type": "integer"
              },
              {
                "name": "limit",
                "description": "Requested number of resources to be provided in response",
                "required": false,
                "in": "query",
                "type": "integer"
              }
            ],
            "responses": {
              "200": {
                "description": "Success",
                "headers": {
                  "X-Result-Count": {
                    "description": "Actual number of items returned in the response body",
                    "type": "integer"
                  },
                  "X-Total-Count": {
                    "description": "Total number of items matching criteria",
                    "type": "integer"
                  }
                },
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/definitions/GeographicLocation"
                  }
                }
              },
              "206": {
                "description": "Partial Content - Partial resource returned in response (with pagination)",
                "headers": {
                  "X-Result-Count": {
                    "description": "Actual number of items returned in the response body",
                    "type": "integer"
                  },
                  "X-Total-Count": {
                    "description": "Total number of items matching criteria",
                    "type": "integer"
                  }
                },
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/definitions/GeographicLocation"
                  }
                }
              },
    
              "400": {
                "description": "Bad Request",
                "schema": {
                  "$ref": "#/definitions/Error"
                }
              },
              "401": {
                "description": "Unauthorized",
                "schema": {
                  "$ref": "#/definitions/Error"
                }
              },
              "403": {
                "description": "Forbidden",
                "schema": {
                  "$ref": "#/definitions/Error"
                }
              },
              "404": {
                "description": "Not Found",
                "schema": {
                  "$ref": "#/definitions/Error"
                }
              },
              "405": {
                "description": "Method Not allowed",
                "schema": {
                  "$ref": "#/definitions/Error"
                }
              },
              "409": {
                "description": "Conflict",
                "schema": {
                  "$ref": "#/definitions/Error"
                }
              },
              "500": {
                "description": "Internal Server Error",
                "schema": {
                  "$ref": "#/definitions/Error"
                }
              }
            }
          }

    This change could be consistently incorporated into all TMF OpenAPIs. This would not even have to be a major update. Any thoughts on this? 

    /Jan



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



  • 4.  RE: Use of HTTP Status 206 for pages

    TM Forum Member
    Posted Mar 10, 2021 04:29
    Hi Jan
    I've passed this on to Open API team colleagues for discussion.
    Watch this space!

    ------------------------------
    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.
    ------------------------------



  • 5.  RE: Use of HTTP Status 206 for pages

    TM Forum Member
    Posted Nov 28, 2022 04:31
    Hi Jonathan, hi @Florin Tene

    I need to bring up this topic again because we are currently discussing pagination and what response code to use.

    RFC9110 is quite clear: when using Range Requests, then use 206. And only then! 

    But what code to use, when you don't use a Range Request but a normal request with pagination/paging (when you don't have any byte content but a list of resources which you want to split into pages) ?

    To our understanding the right response to such a request with paging would be a 200.
    (because with a single page of the list a consumer is fine to work with instead of receiving a part of byte data)

    But "TMF REST API Design Guidelines Part 1, Version 4.0.2, Chapter 4.5.1" uses the 206.

    Are we misunderstanding here something, Chapter 4.5.1 or the RFC9110?

    Somewhat later in the thread you posted that you will pass this topic to the Open API team colleagues.

    Anything new on this topic?

    Kind regards
    Raoul


    ------------------------------
    Raoul Piechatzek
    Deutsche Telekom AG
    ------------------------------



  • 6.  RE: Use of HTTP Status 206 for pages

    TM Forum Member
    Posted Nov 28, 2022 04:42
    Hi @Raoul Piechatzek,

       We've been working on this chapters to provide additional clarifications and I believe in the next release  of the DG this will be clarified.
       In the upcoming DG release, the following separation has been provided:
    Two methods of performing pagination are supported:
    
    1. Offset pagination
    
        - Query Based Style
    
        - Range Header Style
    
    2. Cursor-based pagination​

    And for the off-set based pagination - query based style (so not under the RFC specification for range header style) the recommendation is to use the 200 OK.

    The HTTP Status Code returned by server in the success scenario MUST be 200 OK, complemented of course for all the other HTTP Status Codes relevant for the error scenarios.​

    If you are a member of the TMForum API working group you can access the work in progress version available on the TMForum Github - under the 'tmf630-design-guidelines' repository.

     I hope this helps,

    Thank you,
    Florin

    ------------------------------
    Florin Tene
    CityFibre
    ------------------------------



  • 7.  RE: Use of HTTP Status 206 for pages

    TM Forum Member
    Posted Nov 29, 2022 22:57
    Edited by Vance Shipley Nov 29, 2022 22:57
    On Nov 28, 2022 04:31 @Raoul Piechatzek wrote:
    ​> But what code to use, when you don't use a Range Request but a normal request with pagination/paging (when you don't have any byte content but a list of resources which you want to split into pages) ?

    ​​​Range Requests (RFC7233) are commonly misunderstood to apply only to byte ranges however other Range Units are explicitly supported. While it's true that the IANA Range Unit Registry still only lists bytes the unit items is in common use and specified in TMF630.

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