Open APIs

Expand all | Collapse all

Use of HTTP Status 206 for pages

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