Skip to content

Administration usage

Jump to bottom
José Bonnet edited this page Sep 8, 2017 · 9 revisions

This page details the Administration-related endpoints of the SONATA Gatekeeper API.

At the moment of writing, any user role has access to these endpoints, but this may change in the future. Therefore, all these endpoints are under the anonymous operations type of rate limit (for further details on the rate limit implementation, please check the Integrate the rate limiter wiki page).

/

This endpoint provides the API documentation in Swagger format.

  • Request:
curl <base url>/
  • Response:
---
  swagger: "2.0"
  info: 
    title: "SONATA's SP API"
    description: "This is a proposal for the SONATA's SP API"
    version: "1.0.0"
  host: "sp.sonata-nfv.eu"
  schemes: 
    - "https"
  basePath: "/api/v2"
  produces: 
    - "application/json"
  paths: 
    /: 
      get: 
        summary: "Gatekeeper's URL root"
        description: "Everything starts here"
        operationId: "getRoot"
        tags: 
          - "Root"
        responses: 
          200: 
            description: "This list of paths"
          500: 
            $ref: "#/responses/Standard500ErrorResponse"
    /api-doc: 
      get: 
        summary: "Gatekeeper's API documentation"
        description: "The Gatekeeper's API documentation, in Swagger format"
        operationId: "getApiDoc"
        produces: 
          - "text/html"
        tags: 
          - "API-doc"
        responses: 
          200: 
            description: "This HTML API documentation"
          500: 
            $ref: "#/responses/Standard500ErrorResponse"
    /packages: 
      post: 
        summary: "Submit a SONATA package to the Service Platform"
        description: "The SDK uses this endpoint to submit a SONATA package"
        operationId: "postPackage"
        produces: 
          - "application/json"
        parameters: 
          - 
            name: "package"
            in: "formData"
            description: "The Package file, as specified by the son-schema"
            required: true
            type: "file"
        tags: 
          - "Packages"
        responses: 
          201: 
            description: "The submited package has been received, validated and submited to the Catalogue"
          500: 
            $ref: "#/responses/Standard500ErrorResponse"
      get: 
        summary: "Obtain a list of SONATA packages from the Service Platform, based on its UUID"
        description: "The SDK uses this endpoint to retrieve a SONATA package"
        operationId: "getPackages"
        produces: 
          - "application/json"
          - "application/octet-stream"
        parameters: 
          - 
            in: "query"
            name: "vendor"
            description: "The vendor of the service required"
            required: false
            type: "string"
          - 
            in: "query"
            name: "name"
            description: "The name of the service required"
            required: false
            type: "string"
          - 
            in: "query"
            name: "version"
            description: "The version of the service required"
            required: false
            type: "string"
          - 
            $ref: "#/parameters/offset"
          - 
            $ref: "#/parameters/limit"
        tags: 
          - "Packages"
        responses: 
          200: 
            description: "The required package has been found, and its package is being returned"
          404: 
            $ref: "#/responses/RequiredRecordDoesNotExistResponse"
          500: 
            $ref: "#/responses/Standard500ErrorResponse"
    /packages/{packageId}: 
      get: 
        summary: "Obtain a SONATA package from the Service Platform, based on its UUID"
        description: "The SDK uses this endpoint to retrieve a SONATA package"
        operationId: "getPackage"
        produces: 
          - "application/octet-stream"
        parameters: 
          - 
            in: "path"
            name: "packageId"
            description: "The Package UUID, as provided upon a successful creation of the Package in the Service Platform"
            type: "string"
            required: true
            format: "uuid"
        tags: 
          - "Packages"
        responses: 
          200: 
            description: "The required package has been found, and its file is being returned"
          404: 
            $ref: "#/responses/RequiredRecordDoesNotExistResponse"
          500: 
            $ref: "#/responses/Standard500ErrorResponse"
    /services: 
      get: 
        summary: "Get a list of services"
        description: "Obtain the list of services that can be instantiated"
        operationId: "getServices"
        produces: 
          - "application/json"
        parameters: 
          - 
            in: "query"
            name: "status"
            description: "The status of the services to be returned"
            required: false
            type: "string"
            enum: 
              - "Active"
              - "New"
          - 
            in: "query"
            name: "vendor"
            description: "The vendor of the service required"
            required: false
            type: "string"
          - 
            in: "query"
            name: "name"
            description: "The name of the service required"
            required: false
            type: "string"
          - 
            in: "query"
            name: "version"
            description: "The version of the service required"
            required: false
            type: "string"
          - 
            $ref: "#/parameters/offset"
          - 
            $ref: "#/parameters/limit"
        tags: 
          - "Services"
        responses: 
          200: 
            description: "List of requested services has been returned"
            schema: 
              $ref: "#/definitions/Services"
          404: 
            $ref: "#/responses/RequiredRecordDoesNotExistResponse"
          500: 
            $ref: "#/responses/Standard500ErrorResponse"
    /services/{serviceId}: 
      get: 
        summary: "Get data about a single service"
        description: "Obtain data about the service which (UU)ID is given"
        operationId: "getService"
        produces: 
          - "application/json"
        parameters: 
          - 
            in: "path"
            name: "serviceId"
            description: "The UUID of the required service"
            required: true
            type: "string"
            format: "uuid"
        tags: 
          - "Services"
        responses: 
          200: 
            description: "Data about the given service is returned"
            schema: 
              $ref: "#/definitions/Service"
          404: 
            $ref: "#/responses/RequiredRecordDoesNotExistResponse"
          500: 
            $ref: "#/responses/Standard500ErrorResponse"
    /functions: 
      get: 
        summary: "Get a list of functions"
        description: "Obtain the list of functions"
        operationId: "getFunctions"
        produces: 
          - "application/json"
        parameters: 
          - 
            in: "query"
            name: "status"
            description: "The status of the functions to be returned"
            required: false
            type: "string"
            enum: 
              - "Active"
              - "New"
          - 
            in: "query"
            name: "vendor"
            description: "The vendor of the service required"
            required: false
            type: "string"
          - 
            in: "query"
            name: "name"
            description: "The name of the service required"
            required: false
            type: "string"
          - 
            in: "query"
            name: "version"
            description: "The version of the service required"
            required: false
            type: "string"
          - 
            $ref: "#/parameters/offset"
          - 
            $ref: "#/parameters/limit"
        tags: 
          - "Functions"
        responses: 
          200: 
            description: "List of requested functions has been returned"
          404: 
            $ref: "#/responses/RequiredRecordDoesNotExistResponse"
          500: 
            $ref: "#/responses/Standard500ErrorResponse"
    /functions/{functionId}: 
      get: 
        summary: "Get data about a single function"
        description: "Obtain data about the function which (UU)ID is given"
        operationId: "getFunction"
        produces: 
          - "application/json"
        parameters: 
          - 
            in: "path"
            name: "functionId"
            description: "The UUID of the required function"
            required: true
            type: "string"
            format: "uuid"
        tags: 
          - "Functions"
        responses: 
          200: 
            description: "Data about the given function is returned"
          404: 
            $ref: "#/responses/RequiredRecordDoesNotExistResponse"
          500: 
            $ref: "#/responses/Standard500ErrorResponse"
    /requests: 
      get: 
        summary: "Get the list of instantions requests made"
        description: ""
        operationId: "getRequests"
        produces: 
          - "application/json"
        parameters: 
          - 
            in: "query"
            name: "service_id"
            description: "The UUID of the service of which all requests done are needed"
            required: false
            type: "string"
            format: "uuid"
          - 
            in: "query"
            name: "vendor"
            description: "The vendor of the service required"
            required: false
            type: "string"
          - 
            in: "query"
            name: "name"
            description: "The name of the service required"
            required: false
            type: "string"
          - 
            in: "query"
            name: "version"
            description: "The version of the service required"
            required: false
            type: "string"
          - 
            $ref: "#/parameters/offset"
          - 
            $ref: "#/parameters/limit"
        tags: 
          - "Requests"
        responses: 
          200: 
            description: "Instantiations requests list was returned"
          500: 
            $ref: "#/responses/Standard500ErrorResponse"
      post: 
        summary: "Request the instantion of a given service"
        description: ""
        operationId: "newRequest"
        produces: 
          - "application/json"
        parameters: 
          - 
            in: "body"
            name: "requestId"
            description: "The UUID of the service from which an instance is required"
            required: true
            schema: 
              type: "string"
              format: "uuid"
        tags: 
          - "Requests"
        responses: 
          200: 
            description: "Instantiations requests list was returned"
          404: 
            $ref: "#/responses/RequiredRecordDoesNotExistResponse"
          500: 
            $ref: "#/responses/Standard500ErrorResponse"
    /requests/{requestId}: 
      get: 
        summary: "Get the the given request"
        description: ""
        operationId: "getRequest"
        produces: 
          - "application/json"
        parameters: 
          - 
            in: "path"
            name: "requestId"
            description: "The UUID of the request"
            required: true
            type: "string"
            format: "uuid"
        tags: 
          - "Requests"
        responses: 
          200: 
            description: "Instantiations request data is returned"
          404: 
            $ref: "#/responses/RequiredRecordDoesNotExistResponse"
          500: 
            $ref: "#/responses/Standard500ErrorResponse"
    /vims: 
      get: 
        summary: "Creates a new \"get list of vims\" request and returns its uuid."
        description: ""
        operationId: "getVims"
        produces: 
          - "application/json"
        tags: 
          - "Vims"
        responses: 
          200: 
            description: "Get list of vims request's uuid returned"
          500: 
            $ref: "#/responses/Standard500ErrorResponse"
      post: 
        summary: "Creates a new \"add vim\" request"
        description: ""
        operationId: "newAddVimRequest"
        produces: 
          - "application/json"
        tags: 
          - "Requests"
        responses: 
          200: 
            description: "Add vim request's uuid returned"
          404: 
            $ref: "#/responses/RequiredRecordDoesNotExistResponse"
          500: 
            $ref: "#/responses/Standard500ErrorResponse"
    /vim_requests/{requestId}: 
      get: 
        summary: "Get the the given VIMs request"
        description: ""
        operationId: "getVimRequests"
        produces: 
          - "application/json"
        parameters: 
          - 
            in: "path"
            name: "requestId"
            description: "The UUID of the request"
            required: true
            type: "string"
            format: "uuid"
        tags: 
          - "Requests"
        responses: 
          200: 
            description: "Vim request data is returned"
          404: 
            $ref: "#/responses/RequiredRecordDoesNotExistResponse"
          500: 
            $ref: "#/responses/Standard500ErrorResponse"
    /records: 
      get: 
        summary: "Get the list of all the instances registered"
        description: ""
        operationId: "getInstances"
        produces: 
          - "application/json"
        parameters: 
          - 
            in: "query"
            name: "ownerId"
            description: "The (UU)ID of owner of the service"
            required: false
            type: "string"
          - 
            $ref: "#/parameters/offset"
          - 
            $ref: "#/parameters/limit"
        tags: 
          - "Instances"
        responses: 
          200: 
            description: "Instances list returned"
            schema: 
              $ref: "#/definitions/ServiceInstances"
          500: 
            $ref: "#/responses/Standard500ErrorResponse"
    /records/{instanceId}: 
      get: 
        summary: "Gets a registered instance."
        description: "Returns data on a sigle service instance"
        operationId: "getInstance"
        produces: 
          - "application/json"
        parameters: 
          - 
            in: "path"
            name: "instanceId"
            description: "The UUID of the service instance"
            required: true
            type: "string"
            format: "uuid"
        tags: 
          - "Instances"
        responses: 
          200: 
            description: "Instance data is returned"
            schema: 
              $ref: "#/definitions/ServiceInstance"
          404: 
            $ref: "#/responses/RequiredRecordDoesNotExistResponse"
          500: 
            $ref: "#/responses/Standard500ErrorResponse"
    /micro-services: 
      get: 
        summary: "Get the list of all the registered micro-services"
        description: ""
        operationId: "find"
        produces: 
          - "application/json"
        parameters: 
          - 
            in: "header"
            name: "Authorization"
            description: "The type of authorization required"
            required: false
            type: "string"
          - 
            $ref: "#/parameters/offset"
          - 
            $ref: "#/parameters/limit"
        tags: 
          - "Micro-Services"
        responses: 
          200: 
            description: "Instances list returned"
            schema: 
              $ref: "#/definitions/ServiceInstances"
          500: 
            $ref: "#/responses/Standard500ErrorResponse"
    /micro-services/public-key: 
      get: 
        summary: "Gets User Management module public key."
        description: "Returns User Management module public key, so that 'client' modules can decryt token"
        operationId: "getPublicKey"
        produces: 
          - "application/json"
        tags: 
          - "Micro-Services"
          - "Public Key"
        responses: 
          200: 
            description: "Public Key is returned"
            schema: 
              $ref: "#/definitions/ServiceInstance"
          404: 
            $ref: "#/responses/RequiredRecordDoesNotExistResponse"
          500: 
            $ref: "#/responses/Standard500ErrorResponse"
    /users: 
      get: 
        summary: "Get the list of all the registered users"
        description: ""
        operationId: "find"
        produces: 
          - "application/json"
        parameters: 
          - 
            in: "header"
            name: "Authorization"
            description: "The type of authorization required"
            required: false
            type: "string"
          - 
            $ref: "#/parameters/offset"
          - 
            $ref: "#/parameters/limit"
        tags: 
          - "Users"
        responses: 
          200: 
            description: "Instances list returned"
            schema: 
              $ref: "#/definitions/ServiceInstances"
          500: 
            $ref: "#/responses/Standard500ErrorResponse"
    /users/public-key: 
      get: 
        summary: "Gets User Management module public key."
        description: "Returns User Management module public key, so that 'client' modules can decryt token"
        operationId: "getPublicKey"
        produces: 
          - "application/json"
        tags: 
          - "Micro-Services"
          - "Public Key"
        responses: 
          200: 
            description: "Public Key is returned"
            schema: 
              $ref: "#/definitions/ServiceInstance"
          404: 
            $ref: "#/responses/RequiredRecordDoesNotExistResponse"
          500: 
            $ref: "#/responses/Standard500ErrorResponse"
  definitions: 
    Service: 
      required: 
        - "serviceId"
      properties: 
        serviceId: 
          type: "string"
          format: "uuid"
        name: 
          type: "string"
        vendor: 
          type: "string"
        version: 
          type: "string"
        created_at: 
          type: "string"
          format: "date"
        updated_at: 
          type: "string"
          format: "date"
    Services: 
      type: "array"
      items: 
        $ref: "#/definitions/Service"
    ServiceInstance: 
      required: 
        - "instanceId"
        - "serviceId"
      properties: 
        instanceId: 
          type: "string"
          format: "uuid"
        serviceId: 
          type: "string"
          format: "uuid"
        created_at: 
          type: "string"
          format: "date"
        updated_at: 
          type: "string"
          format: "date"
    ServiceInstances: 
      type: "array"
      items: 
        $ref: "#/definitions/ServiceInstance"
    Error: 
      properties: 
        code: 
          type: "string"
        message: 
          type: "string"
  responses: 
    Standard500ErrorResponse: 
      description: "An unexpected error occured."
      schema: 
        $ref: "#/definitions/Error"
    RequiredRecordDoesNotExistResponse: 
      description: "The required record does not exist"
      schema: 
        $ref: "#/definitions/Error"
  parameters: 
    limit: 
      name: "limit"
      in: "query"
      description: "Number of service instances to return. Default is 5, maximum is 100"
      type: "integer"
    offset: 
      name: "offset"
      in: "query"
      description: "Offset the list of returned results by this amount. Default is zero"
      type: "integer"

/admin/logs

This endpoint returns the content of the logs of the api micro-service.

  • Request:

curl <base url>/admin/logs
  • Response:
...
D, [2017-09-08 08:31:11#8] DEBUG -- GtkApi:: GET /api/v2/services: links: request_url=http://sp.int3.sonata-nfv.eu/api/v2/services, limit=10, offset=0, total=1
D, [2017-09-08T08:31:11.318371 #8] DEBUG -- GtkApi: Schema=http, host=sp.int3.sonata-nfv.eu, path=/api/v2/services
D, [2017-09-08 08:31:11#8] DEBUG -- GtkApiHelper.build_pagination_headers: url: http://sp.int3.sonata-nfv.eu/api/v2/services, limit: 10, offset: 0, total: 1
D, [2017-09-08 08:31:11#8] DEBUG -- GtkApi:: GET /api/v2/services: links: <http://sp.int3.sonata-nfv.eu/api/v2/services?offset=0&limit=10>; rel="first",<http://sp.int3.sonata-nfv.eu/api/v2/services?offset=0&limit=10>; rel="last"
D, [2017-09-08T08:31:11.318531 #8] DEBUG -- GtkApi::KpiManagerService#update_metric: entered with {:job=>"sonata", :instance=>"gtkapi", :metric_type=>"counter", :name=>"services_metadata_queries", :docstring=>"how many service metadata queries have been made", :base_labels=>{:result=>"ok", :uuid=>"", :elapsed_time=>"0.103654518", :method=>"GET", :module=>"services", :time_stamp=>2017-09-08 08:31:11 UTC}}
D, [2017-09-08T08:31:11.318560 #8] DEBUG -- GtkApi::KpiManagerService#update_metric: url = http://sp.int3.sonata-nfv.eu:5400
D, [2017-09-08T08:31:11.318616 #8] DEBUG -- GtkApi::ManagerService#putCurb: entered with url=http://sp.int3.sonata-nfv.eu:5400/kpis, body={"job":"sonata","instance":"gtkapi","metric_type":"counter","name":"services_metadata_queries","docstring":"how many service metadata queries have been made","base_labels":{"result":"ok","uuid":"","elapsed_time":"0.103654518","method":"GET","module":"services","time_stamp":"2017-09-08 08:31:11 UTC"}}
D, [2017-09-08T08:31:11.413009 #8] DEBUG -- GtkApi::ManagerService#putCurb: response body=
D, [2017-09-08T08:31:11.413059 #8] DEBUG -- GtkApi::ManagerService#putCurb: status 201, parsed_response=[]
E, [2017-09-08T08:31:11.413095 #8] ERROR -- GtkApi::KpiManagerService#update_metric: response={:status=>201, :count=>1, :items=>[], :message=>"OK"}
172.20.0.34 - - [08/Sep/2017:08:31:11 +0000] "GET /api/v2/services HTTP/1.0" 200 1748 0.1991
D, [2017-09-08 08:31:14#8] DEBUG -- GtkApi GET /admin/logs: entered

/admin/<micro-service name>/logs

This endpoint returns the content of the logs of the micro-service given in the URL (for a list of available micro-service names see the next section, on the /available-services endpoint).

  • Request:
curl <base url>/admin/packages/logs
  • Response:
...
D, [2017-09-08 08:24:19#7] DEBUG -- GtkPkg:: GET "/packages/?offset=0&limit=10": entered
D, [2017-09-08T08:24:19.015749 #7] DEBUG -- Catalogue.find: params={"offset"=>"0", "limit"=>"10"}, headers={"Accept"=>"application/json", "Content-Type"=>"application/json", :params=>{"offset"=>"0", "limit"=>"10"}}
D, [2017-09-08T08:24:19.049483 #7] DEBUG -- Catalogue.find: response was [{"created_at":"2017-09-08T01:48:18.377+00:00","md5":"510341c643b740192d08d85143d68c49","pd":{"description":"SONATA vTC Y1 demo service","descriptor_version":"1.0","entry_service_template":"/service_descriptors/sonata-demo.yml","maintainer":"Steven Van Rossem, Ghent University","name":"sonata-vtc-service-sp","package_content":[{"content-type":"application/sonata.service_descriptor","md5":"9e87f0349779603960dfea601280298e","name":"/service_descriptors/sonata-demo.yml"},{"content-type":"application/sonata.function_descriptor","md5":"e84bc7ba1a5045d560fbff4ade9f95b5","name":"/function_descriptors/vtc-vnf-vnfd.yml"}],"schema":"https://raw.githubusercontent.com/sonata-nfv/son-schema/master/package-descriptor/pd-schema.yml","sealed":true,"vendor":"eu.sonata-nfv.package","version":"0.4"},"signature":null,"son_package_uuid":"106d4825-34fe-44eb-874a-1c76104790e4","status":"active","updated_at":"2017-09-08T01:48:18.789+00:00","username":"jenkins","uuid":"5b7544d2-a3c9-4618-b049-ec363e135f6d"}]
D, [2017-09-08 08:24:19#7] DEBUG -- GtkPkg:: GET "/packages/?offset=0&limit=10": packages: [{"created_at"=>"2017-09-08T01:48:18.377+00:00", "md5"=>"510341c643b740192d08d85143d68c49", "pd"=>{"description"=>"SONATA vTC Y1 demo service", "descriptor_version"=>"1.0", "entry_service_template"=>"/service_descriptors/sonata-demo.yml", "maintainer"=>"Steven Van Rossem, Ghent University", "name"=>"sonata-vtc-service-sp", "package_content"=>[{"content-type"=>"application/sonata.service_descriptor", "md5"=>"9e87f0349779603960dfea601280298e", "name"=>"/service_descriptors/sonata-demo.yml"}, {"content-type"=>"application/sonata.function_descriptor", "md5"=>"e84bc7ba1a5045d560fbff4ade9f95b5", "name"=>"/function_descriptors/vtc-vnf-vnfd.yml"}], "schema"=>"https://raw.githubusercontent.com/sonata-nfv/son-schema/master/package-descriptor/pd-schema.yml", "sealed"=>true, "vendor"=>"eu.sonata-nfv.package", "version"=>"0.4"}, "signature"=>nil, "son_package_uuid"=>"106d4825-34fe-44eb-874a-1c76104790e4", "status"=>"active", "updated_at"=>"2017-09-08T01:48:18.789+00:00", "username"=>"jenkins", "uuid"=>"5b7544d2-a3c9-4618-b049-ec363e135f6d"}]
D, [2017-09-08 08:24:19#7] DEBUG -- GtkPkg:: GET "/packages/?offset=0&limit=10": leaving with 1 package(s) found
172.20.0.1 - - [08/Sep/2017:08:24:19 +0000] "GET /packages?offset=0&limit=10 HTTP/1.1" 200 998 0.0347
D, [2017-09-08 08:35:14#7] DEBUG -- : GtkPkg: entered GET /admin/logs

/available-services

This endpoint returns a list of the available micro-services. Each element of the list consists of three fields:

  • alive_since: the date since the micro-service is running;
  • name: the name of the micro-service;
  • seconds: the time for how long in seconds the service is running.

When a micro-service does not implement the internal API needed to retrieve alive_since and calculate seconds, the value null is given to both these fields.

  • Request:
curl <base url>/api/v2/available-services
  • Response:
[
    {
        "alive_since": "2017-09-08 00:14:33 UTC", 
        "name": "api", 
        "seconds": 29104.857606581
    }, 
    {
        "alive_since": "2017-09-08 00:13:44 UTC", 
        "name": "packages", 
        "seconds": 29154.772184473
    }, 
    {
        "alive_since": null, 
        "name": "services", 
        "seconds": null
    }, 
    {
        "alive_since": null, 
        "name": "functions", 
        "seconds": null
    }, 
    {
        "alive_since": null, 
        "name": "records", 
        "seconds": null
    }, 
    {
        "alive_since": null, 
        "name": "licences", 
        "seconds": null
    }, 
    {
        "alive_since": "2017-09-08T00:14:09.682Z", 
        "name": "vims", 
        "seconds": 29129.090184473
    }, 
    {
        "alive_since": "2017-09-08T00:14:09.682Z", 
        "name": "wims", 
        "seconds": 29129.090184473
    }, 
    {
        "alive_since": null, 
        "name": "kpis", 
        "seconds": null
    }, 
    {
        "alive_since": null, 
        "name": "users", 
        "seconds": null
    }, 
    {
        "alive_since": null, 
        "name": "micro-services", 
        "seconds": null
    }, 
    {
        "alive_since": null, 
        "name": "catalogue", 
        "seconds": null
    }, 
    {
        "alive_since": null, 
        "name": "metrics", 
        "seconds": null
    }, 
    {
        "alive_since": null, 
        "name": "validator", 
        "seconds": null
    }, 
    {
        "alive_since": null, 
        "name": "rate_limiter", 
        "seconds": null
    }
]

Clone this wiki locally