Microservices Assessment Platform API documentation

The Microservices Assessment Platform has a GraphQL-based API.

Here is an example query:

curl https://platform.microservices.io/graphql \
--user "accessKeyId:accessKeySecret" \
--data-binary '{"query":"query applications {  applications { id, name }}"}'

Here is the response:

{
  "data": {
    "applications": [
        {
            "id": "8013da5c-59b3-421e-b8a6-8d5607754c4c",
            "name": "My Application"
        }
    ]
  }
}

Got questions?

If you have questions or feedback please

Create an issue
Post in the Slack Workspace Join

Getting an API key

To use the API you need an API key and secret. You can generate these in the console.

Step 1: From the user menu select 'Settings…'

to navigate to the Settings page.

Step 2: From this page, press on 'Access Keys' button:

How to Generate Keys in the Console

From the Access Keys Management Page, press the 'Generate' button:

In a few moments the Access Key ID and the Secret Access Key will have been generated, the examples will have these values incorporated in them:

Schema

    type Application {
        id: String
        name: String,
        created: Long,
        modified: Long,
        services: [Service],
        service(name : String!): Service
        assessments: [Assessment],
        latestCompletedAssessment: Assessment
    }

    type Service {
        id: String
        name: String
        created: Long,
        modified: Long,
        assessments: [Assessment]
        latestCompletedAssessment: Assessment
    }

    type Organization {
        name: String
        applications: [Application]
        application(name: String!): [Application]
    }

    type Assessment {
        id: String
        name: String
        state: AssessmentState
        created: Long
        modified: Long,
        answers: [AssessmentSection]
        topLevelScore: Int
    }
    
    enum AssessmentState {
        IN_PROGRESS
        COMPLETED
        ABANDONED
    }
    
    type Answer {
        question: String # The question title
        answer: String # The answer title
    }

    type AssessmentSection {
        section: String # The section title
        score: Int
        answers: [Answer]
    }
    
    type Query {
        applications: [Application]
        application(name: String!): [Application]
        uniqueApplication(name: String!): Application
        applicationById(id: String!): Application
        organizations: [Organization]
        organization(name: String!): [Organization]
    }

    type Mutation {
        createApplicationForUser(name: String): Application

        createApplicationInOrganization(
            organization: String
            name: String
        ): Application

        createServiceForUser(applicationName : String serviceName : String): Service

        createServiceInOrganization(
            organization: String
            applicationName: String
            serviceName : String
        ): Service
    }

Success and error responses

Success response

HTTP Status: 200

Response:

{
  "data": {
    "applications": [
        {
            "id": "8013da5c-59b3-421e-b8a6-8d5607754c4c",
            "name": "My Application"
        }
    ]
  }
}

Error response

HTTP Status: 200

Response:

{
  "errors": [
    {
      "statusCode": 403,
      "errorCode": 403,
      "message": "Forbidden"
    }
  ]
}

Example requests

Retrieve user applications with the last completed assessments

{
    "query": "query {
        applications {
            id, name, created, modified,
            latestCompletedAssessment {
                name,
                topLevelScore,
                answers { section, score, answers { question, answer } }
            }
        }
    }"
}

Retrieve applications list by name

{
    "query": "query
        application($name: String!) {
            application(name: $name) {
                id, name, created, modified,
                services {
                    id, name, created, modified,
                    assessments {
                        name,
                        topLevelScore,
                        answers { section, score, answers { question, answer } }
                    },
                    latestCompletedAssessment {
                        name,
                        topLevelScore,
                        answers { section, score, answers { question, answer } }
                    }
                },
                assessments {
                    name,
                    topLevelScore,
                    answers { section, score, answers { question, answer } }
                },
                latestCompletedAssessment {
                    name,
                    topLevelScore,
                    answers { section, score, answers { question, answer } }
                }
            }
        }",
    "variables": { "name": "Example application" }
}

Retrieve application by ID

{
    "query": "query
        applicationById($id: String!) {
            applicationById(id: $id) { id, name, created, modified }
        }",
    "variables":{ "id": "f3afc470-fc2a-11ea-87a7-b360a6f25f3a" }
}

Retrieve organizations list

{
    "query": "query {
        organizations { name, applications { id, name, created, modified } }
    }"
}

Retrieve organization by name

{
    "query": "query organization($name: String!) {
        organization(name: $name) { name }
    }",
    "variables": { "name":"My Organization" }
}

Retrieve organization by name and find application within organization

{
    "query": "query organization($name: String!, $applicationName: String!) {
        organization(name: $name) {
            name,
            application (name: $applicationName) { name }
        }
    }",
    "variables": { "name":"My Organization", "applicationName": "My Application" }
}

Mutations

Create application

{
    "query": "mutation CreateApplicationForUserMutation($name: String) {
        createApplicationForUser(name: $name) { id }
    }",
    "variables": { "name":"My Application" }
}

Create application in organization

{
    "query": "mutation CreateApplicationInOrganizationMutation($organization: String, $name: String) {
        createApplicationInOrganization(organization: $organization, name: $name) { id }
    }",
    "variables":{
        "name": "My Application",
        "organization": "My Organization"
    }
}

Create service

{
    "query": "mutation createServiceForUser($serviceName: String, $applicationName: String) {
        createServiceForUser(serviceName: $serviceName, applicationName: $applicationName) { id } }",
    "variables": {
        "serviceName": "My Service",
        "applicationName": "My Application"
    }
}

Create service in organization

{
    "query": "mutation createServiceInOrganization($organization: String, $applicationName: String, $serviceName: String) {
        createServiceInOrganization(organization: $organization, applicationName: $applicationName, serviceName: $serviceName) { id }
    }",
    "variables": {
        "organization": "My Organization",
        "applicationName": "My Application",
        "serviceName": "My Service"
    }
}