openapi: 3.0.3
info:
  description: This OAS file describes the NGSI-LD API defined by the ETSI ISG CIM group. This Cross-domain Context Information Management API allows to provide, consume and subscribe to context information in multiple scenarios and involving multiple stakeholders
  version: latest
  title: ETSI ISG CIM / NGSI-LD API Entry Point Attribute Value API
  contact:
    email: NGSI-LD@etsi.org
tags:
- name: Attribute Value
paths:
  /v2/entities/{entityId}/attrs/{attrName}/value:
    get:
      description: "This operation returns the `value` property with the value of the attribute.\n* If attribute value is JSON Array or Object:\n  * If `Accept` header can be expanded to `application/json` or `text/plain` return the value as a JSON with a\n    response type of application/json or text/plain (whichever is the first in `Accept` header or\n    `application/json` in case of `Accept: */*`).\n  * Else return a HTTP error \"406 Not Acceptable: accepted MIME types: application/json, text/plain\"\n* If attribute value is a string, number, null or boolean:\n  * If `Accept` header can be expanded to text/plain return the value as text. In case of a string, citation\n    marks are used at the begining and end.\n  * Else return a HTTP error \"406 Not Acceptable: accepted MIME types: text/plain\"\nResponse:\n* Successful operation uses 200 OK.\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n  more details."
      summary: Get Attribute Value
      tags:
      - Attribute Value
      operationId: Get Attribute Value
      produces:
      - application/json
      parameters:
      - name: entityId
        in: path
        required: true
        type: string
        description: Id of the entity in question
      - name: attrName
        in: path
        required: true
        type: string
        description: Name of the attribute to be retrieved.
      - name: type
        in: query
        required: false
        type: string
        description: 'Entity type, to avoid ambiguity in case there are several

          entities with the same entity id.'
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/GetAttributeValueResponse'
          examples:
            application/json:
              address: Ronda de la Comunicacion s/n
              zipCode: 28050
              city: Madrid
              country: Spain
      x-unitTests:
      - request:
          method: GET
          uri: /v2/entities/Bcn_Welt/attrs/address/value
        expectedResponse:
          x-allowExtraHeaders: true
          x-bodyMatchMode: RAW
          x-arrayOrderedMatching: false
          x-arrayCheckCount: false
          x-matchResponseSchema: true
          headers:
            Content-Type: application/json
          body: '{  "address": "Ronda de la Comunicacion s/n",  "zipCode": 28050,  "city": "Madrid",  "country": "Spain"}'
        x-testShouldPass: true
        x-testEnabled: true
        x-testName: Get Attribute Value1
        x-testDescription: "This operation returns the `value` property with the value of the attribute.\n* If attribute value is JSON Array or Object:\n  * If `Accept` header can be expanded to `application/json` or `text/plain` return the value as a JSON with a\n    response type of application/json or text/plain (whichever is the first in `Accept` header or\n    `application/json` in case of `Accept: */*`).\n  * Else return a HTTP error \"406 Not Acceptable: accepted MIME types: application/json, text/plain\"\n* If attribute value is a string, number, null or boolean:\n  * If `Accept` header can be expanded to text/plain return the value as text. In case of a string, citation\n    marks are used at the begining and end.\n  * Else return a HTTP error \"406 Not Acceptable: accepted MIME types: text/plain\"\nResponse:\n* Successful operation uses 200 OK.\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n  more details."
      x-operation-settings:
        CollectParameters: false
        AllowDynamicQueryParameters: false
        AllowDynamicFormParameters: false
        IsMultiContentStreaming: false
    put:
      description: "The request payload is the new attribute value.\n* If the request payload MIME type is `application/json`, then the value of the attribute is set to\n  the JSON object or array coded in the payload (if the payload is not a valid JSON document,\n  then an error is returned).\n* If the request payload MIME type is `text/plain`, then the following algorithm is applied to the\n  payload:\n  * If the payload starts and ends with citation-marks (`\"`), the value is taken as a string\n    (the citation marks themselves are not considered part of the string)\n  * If `true` or `false`, the value is taken as a boolean.\n  * If `null`, the value is taken as null.\n  * If these first three tests 'fail', the text is interpreted as a number.\n  * If not a valid number, then an error is returned and the attribute's value is unchanged.\nThe payload MIME type in the request is specified in the `Content-Type` HTTP header.\nResponse:\n* Successful operation uses 204 No Content\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n  more details."
      summary: Update Attribute Value
      tags:
      - Attribute Value
      operationId: Update Attribute Value
      produces:
      - application/json
      parameters:
      - name: entityId
        in: path
        required: true
        type: string
        description: Id of the entity to be updated.
      - name: attrName
        in: path
        required: true
        type: string
        description: Attribute name.
      - name: Content-Type
        in: header
        required: true
        type: string
        description: ''
      - name: body
        in: body
        required: true
        description: ''
        schema:
          $ref: '#/definitions/UpdateAttributeValueRequest'
      - name: type
        in: query
        required: false
        type: string
        description: 'Entity type, to avoid ambiguity in case there are several

          entities with the same entity id.'
      responses:
        '200':
          description: ''
      x-unitTests:
      - request:
          method: PUT
          uri: /v2/entities/Bcn_Welt/attrs/address/value
          headers:
            Content-Type: application/json
          body: '{  "address": "Ronda de la Comunicacion s/n",  "zipCode": 28050,  "city": "Madrid",  "country": "Spain"}'
        expectedResponse:
          x-allowExtraHeaders: true
          x-bodyMatchMode: NONE
          x-arrayOrderedMatching: false
          x-arrayCheckCount: false
          x-matchResponseSchema: true
          headers: {}
        x-testShouldPass: true
        x-testEnabled: true
        x-testName: Update Attribute Value1
        x-testDescription: "The request payload is the new attribute value.\n* If the request payload MIME type is `application/json`, then the value of the attribute is set to\n  the JSON object or array coded in the payload (if the payload is not a valid JSON document,\n  then an error is returned).\n* If the request payload MIME type is `text/plain`, then the following algorithm is applied to the\n  payload:\n  * If the payload starts and ends with citation-marks (`\"`), the value is taken as a string\n    (the citation marks themselves are not considered part of the string)\n  * If `true` or `false`, the value is taken as a boolean.\n  * If `null`, the value is taken as null.\n  * If these first three tests 'fail', the text is interpreted as a number.\n  * If not a valid number, then an error is returned and the attribute's value is unchanged.\nThe payload MIME type in the request is specified in the `Content-Type` HTTP header.\nResponse:\n* Successful operation uses 204 No Content\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n  more details."
      x-operation-settings:
        CollectParameters: false
        AllowDynamicQueryParameters: false
        AllowDynamicFormParameters: false
        IsMultiContentStreaming: false
definitions:
  UpdateAttributeValueRequest:
    title: Update Attribute Value request
    example:
      address: Ronda de la Comunicacion s/n
      zipCode: 28050
      city: Madrid
      country: Spain
    type: object
    properties:
      address:
        description: ''
        example: Ronda de la Comunicacion s/n
        type: string
      zipCode:
        description: ''
        example: 28050
        type: integer
        format: int32
      city:
        description: ''
        example: Madrid
        type: string
      country:
        description: ''
        example: Spain
        type: string
    required:
    - address
    - zipCode
    - city
    - country
  GetAttributeValueResponse:
    title: Get Attribute Value response
    example:
      address: Ronda de la Comunicacion s/n
      zipCode: 28050
      city: Madrid
      country: Spain
    type: object
    properties:
      address:
        description: ''
        example: Ronda de la Comunicacion s/n
        type: string
      zipCode:
        description: ''
        example: 28050
        type: integer
        format: int32
      city:
        description: ''
        example: Madrid
        type: string
      country:
        description: ''
        example: Spain
        type: string
    required:
    - address
    - zipCode
    - city
    - country
externalDocs:
  description: Find out more about the ETSI ISG Context Information Management
  url: https://portal.etsi.org/tb.aspx?tbid=854&SubTB=854