Skip to main content

Introduction

Search and display certificate information. Order, renew and revoke your certificates and export your certificates portfolio.

info
{GET|POST|DELETE} /ssl/v2/{resource}

JSON:API​

Certificates API follows the JSON:API specification. Which means any resources returned by the API will be returned in this format:

{
   "data": {
      "type": "{resource}",
      "id": "ABC012",
      "links": {
        "self": "https://api.nameshield.net/ssl/v2/{resource}/ABC012"
      },
      "attributes": {
        // resource data
        "property": "value"
      },
      "relationships": {
        // resource relationships
        "{related resource}": {
          "links": {
            "related": "https://essl.nameshield.blue/ssl/v2/{resource}/ABC012/{related resource}"
          },
          "data": {
            "type": "{related resource}",
            "id": "ABC012"
          }
        }
      }
    }
}
example

For example, this is a sample certificate resource:

See sample

{
  "data": {
    "type": "certificate",
    "id": "ABC012",
    "links": {
      "self": "https://apinms.int.perf1.net/ssl/v2/certificates/1"
    },
    "attributes": {
      "status": "waiting",
      "common_name": "test.fr",
      "sans": [
        "test.test.fr",
        "nms.test.eu"
      ],
      "serial": "263ED182F7FB230E0AD3DDAEA3DF7D88",
      "customer_id": 1234,
      "validity_start": "2022-03-31",
      "validity_end": "2024-03-31"
    },
    "relationships": {
      "organization": {
        "links": {
          "related": "https://apinms.int.perf1.net/ssl/v2/certificates/1/organization"
        },
        "data": {
          "type": "organization",
          "id": "ABC012"
        }
      },
      "product": {
        "links": {
          "related": "https://apinms.int.perf1.net/ssl/v2/certificates/1/product"
        },
        "data": {
          "type": "product",
          "id": "ABC012"
        }
      },
      "comments": {
        "links": {
          "related": "https://apinms.int.perf1.net/ssl/v2/certificates/1/comments"
        },
        "data": [
          {
            "type": "comment",
            "id": "ABC012"
          }
        ]
      },
      "current-order": {
        "links": {
          "related": "https://apinms.int.perf1.net/ssl/v2/certificates/1/current-order"
        },
        "data": {
          "type": "order",
          "id": "ABC012"
        }
      },
      "contacts": {
        "links": {
          "related": "https://apinms.int.perf1.net/ssl/v2/orders/1/contacts"
        },
        "data": [
          {
            "type": "contact",
            "id": "ABC012",
            "meta": {
              "contact_type": "admin"
            }
          },
          {
            "type": "contact",
            "id": "ABC012",
            "meta": {
              "contact_type": "tech"
            }
          }
        ]
      }
    }
  }
}

Single resource endpoints will return data in this format:

{
    "data": {
        // resource
    }
}

List endpoints will return data and pagination information in this format:

{
    "data": [
        // resources
    ],
    "links": {
        "self": "https://api.nameshield.net/ssl/v2/{resource}?page[number]=4",
        "first": "https://api.nameshield.net/ssl/v2/{resource}?page[number]=1",
        "last": "https://api.nameshield.net/ssl/v2/{resource}?page[number]=20",
        "prev": "https://api.nameshield.net/ssl/v2/{resource}?page[number]=3",
        "next": "https://api.nameshield.net/ssl/v2/{resource}?page[number]=5"
    },
    "meta": {
        "page_size": 10,
        "total": 200
    }
}

Specific query parameters​

All list endpoints follows the same query principle with 4 query parameters:

  • page: pagination
  • fields: resources fields configuration (also available for single resources)
  • filter: resource filtering
  • search: resource searching
  • include: compound documents (also available for single resources)

Page​

Pagination works as follows:

page[size]={page_size}&page[number]={page_number}

See JSON:API - Pagination

Fields​

To restrict or add hidden fields to your results (lists or single resources), you can add the fields query parameter:

fields[{resource_name}]={field_name_1},{field_name_2}
info

You can find available fields on each resources documentation.

example

If you want to query statuses along with certificates X.509 you can query:

GET /ssl/v2/certificates?fields[certificate]=status,x509

See JSON:API - Sparse Fieldsets

Filter​

To filter a list you can do so by adding the filter query parameter:

filter[{field_name}]={value_1},{value_2}
info

You can find available values on each resources documentation.

example

If you want to get expired and revoked certificates you can query:

GET /ssl/v2/certificates?filter[status]=expired,revoked

See JSON:API - Filtering

To search in a list you can do so by adding the search query parameter:

search[{field_name}]={value}
caution

It can be simplified as searching %value% in SQL so be careful how you enter your search input.

example

If you want to search a certificates ending with a date containing "2023-03" you can query:

GET /ssl/v2/certificates?search[validity_end]=2023-03

(This query will return certificates ending in May 2023)

Include​

To get other resources from relationships, you can do so by adding the include query parameter as a comma separated list of resource types. The response will have an included key that contains said resources:

include={resource_type_1},{resource_type_2},...
example

If you want to have the organization included with certificate informations:

GET /ssl/v2/certificates?include=organization

(This query will return certificates and their respective organizations)

See JSON:API - Inclusion of Related Resources & JSON:API - Compound Documents