Service specification

Before you start

If you haven't done it yet, read about services' main concepts.

Also have these handy reference:

• Service Specification API [ POST | PATCH | GET | LIST | DELETE ]
• Schemas
  • JSON Schema (external link) | Additional keywords supported by nullplatform
  • UI Schema (external link) | How UI schema is integrated in nullplatform

Design your service specification

Before actually creating the service, you have to answer yourself some questions that we'll present in a table, so you can see how your answers impact your service specification:

Question	Guidance
What's the name for the service?	Choose a natural name (e.g., MySQL) and set it into the name field.
Which properties do I need to hold for the service?	These are the properties that define the service. They are usually a combination of input parameters plus values obtained from the cloud provider upon service creation. Set these as a JSON schema in the attributes field.
Where in the organization is the service going to be available?	A good default is to start by making the service visible everywhere with the value organization=your-org-id:account=*. Set your choice in the visible_to array.

Create a service specification

The first step in the journey is to create the service specification like this:

CLI

np service-specification create \
 --body '{
    "name": "my-service-specification",
    "type": "dependency",
    "visible_to": [
      "organization=1:account=1",
      "organization=1:account=2"
    ],
    "attributes": {         //defines the structure and layout of the form. 
      "schema": {
        "type": "object",
        "properties": {
          "my_string_property": {
            "type": "string"
          },
          "my_number_property": {
            "type": "number",
            "default": 0
          }
        },
        "required": [
          "my_string_property"
        ]
      },
      "values": {}
    }
  }'

cURL

curl -L 'https://api.nullplatform.com/service_specification' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer the-token' \
-d '{
  "name": "my-service-specification",
  "type": "dependency",
  "visible_to": [
    "organization=1:account=2:namespace=3",
    "organization=1:account=2:namespace=4"
  ],
  "attributes": { 
    "schema": {
      "type": "object",
      "properties": {
        "my_string_property": {
          "type": "string"
        },
        "my_number_property": {
          "type": "number",
          "default": 0
        }
      },
      "required": [
        "my_string_property"
      ]
    },
    "values": {}
  }
}'

Service details

The JSON schema under attributes determines the service's attributes, therefore those properties will become available in the See details section of nullplatform's UI. You can further enhance the rendering of that section using UI Schema.

Some attributes to consider

Let's do more digging into some of the fields we have included in the JSON:

• visible_to: visibility scope for the entity as NRN. Each entry in this array follows the format organization=<org_id>:account=<account_id>:namespace=<namespace_id>. For example:

  • "organization=1:account=2:namespace=3" makes the service visible to namespace 3 under account 2 of organization 1.
  • "organization=1:account=2:namespace=*" makes the service visible to all namespaces under account 2.

• attributes: describes the configuration required for the service in a JSON schema format.