# Planning Status API

## Context

With the Planning Status API you can fetch the status of the planning. The status indicates which steps the data you
have sent to our platform went through.

## Environment

For the Planning Status API we use the following URIs:

Production URL:


```
https://planning-status-api.services.simacan.com/api/v4/attempts/{uuid}
```

Staging URL:


```
https://planning-status-api-stg.services.simacan.com/api/v4/attempts/{uuid}
```

## Schema

The planning-status-api is a *read-only* API and thus only supports GET requests.

The exact schema can be found on [our OpenAPI specification](https://planning-status-api.services.simacan.com/api/v4).

## Example

### Getting the status

In a previous step, you delivered your data to our platform and if everything went fine, you should have obtained an
UUID. In our previous example we got `01b44637-1395-4591-a0ec-14108022b707`

#### Request it

Keep in mind that this request only works, if you have a bearer token. Include this in the header.
In this example we request the staging environment.


```shell
curl -H "Authorization: Bearer eyXXX" -X GET -i https://planning-status-api-stg.services.simacan.com/api/v4/attempts/01b44637-1395-4591-a0ec-14108022b707
```

#### Response

If everything went fine, you should receive an HTTP status code 200 OK and a body which looks like this


```json
{
  "importAttempt" : {
    "id" : "39e8d454-87b4-427d-a4f3-c50ed2677644",
    "name" : "peterson/2020-09-02T12:26:47.585271Z.json",
    "planningCreationTime" : "2020-09-02T12:26:47.705Z",
    "shipper" : "peterson",
    "triggerType" : "Automatic",
    "status" : "ShouldStart",
    "file" : {
      "fileName" : "peterson/2020-09-02T12:26:47.585271Z.json",
      "directory" : "simacan-planning-data"
    },
    "tags" : {
      "mimeType" : "application/json",
      "version" : 1,
      "schema" : "json",
      "source" : "planning-receive-api"
    }
  },
  "steps" : [ {
    "id" : "90e66fcb-4be0-4d33-9ee6-60fe999904e5",
    "endTime" : "2020-09-02T12:26:47.708852Z",
    "status" : "ShouldStart",
    "errors" : [ ],
    "name" : "Starting peterson/2020-09-02T12:26:47.585271Z.json",
    "processingStepType" : "Starting"
  } ],
  "items" : [ ]
}
```

When consuming this response, check for the `status`. The value for status can be `ShouldStart`, `Running`, `Succeeded` or `Failed`.
In this case `ShouldStart` would mean that the specific file has been received by Simacan, but the processing of it,
should still be starting. When requesting a bit later, you should see more `steps`, where you can analyze all steps
taken on your planning file. Ultimately you are looking for the status `Succeeded`

#### Failed response

Of course not all files will be processed properly. To give you an idea on how a failed attempt will look like, we've
sent a malformed JSON file to the Planning Receive API. What follows is a response, for when processing has failed.


```json
{
  "importAttempt" : {
    "id" : "39e8d454-87b4-427d-a4f3-c50ed2677644",
    "name" : "peterson/2020-09-02T12:26:47.585271Z.json",
    "planningCreationTime" : "2020-09-02T12:26:47.705Z",
    "shipper" : "peterson",
    "triggerType" : "Automatic",
    "status" : "Failed",
    "file" : {
      "fileName" : "peterson/2020-09-02T12:26:47.585271Z.json",
      "directory" : "simacan-planning-data"
    },
    "tags" : {
      "mimeType" : "application/json",
      "version" : 1,
      "schema" : "json",
      "source" : "planning-receive-api"
    }
  },
  "steps" : [ {
    "id" : "9a00f442-2806-4e15-adec-de005ec7240f",
    "endTime" : "2020-09-02T12:40:05.553Z",
    "status" : "Failed",
    "errors" : [ {
      "id" : "15b245b0-6a47-44ae-8bf2-591f430cd368",
      "message" : "(/_id,List(JsonValidationError(List(error.path.missing),WrappedArray())))"
    }, {
      "id" : "0cf9c82d-aecd-428e-9c0d-51dbab47f47b",
      "message" : "(/id,List(JsonValidationError(List(error.path.missing),WrappedArray())))"
    }, {
      "id" : "9a2066e4-01b4-4553-9416-a5600b43f761",
      "message" : "(/timestamp,List(JsonValidationError(List(error.path.missing),WrappedArray())))"
    }, {
      "id" : "daedc47f-378d-4db0-910b-672ff0e4899d",
      "message" : "(/tripid,List(JsonValidationError(List(error.path.missing),WrappedArray())))"
    }, {
      "id" : "1e020fe8-399d-4311-a64b-1f64473624ea",
      "message" : "(/planning,List(JsonValidationError(List(error.path.missing),WrappedArray())))"
    }, {
      "id" : "db329e8a-e019-4964-833c-5e09ef2fc307",
      "message" : "(/clientname,List(JsonValidationError(List(error.path.missing),WrappedArray())))"
    } ],
    "name" : "Converting JSON to domain",
    "processingStepType" : "ConvertToDomain"
  }, {
    "id" : "a909d69d-a80b-4364-9bc1-33442803a541",
    "endTime" : "2020-09-02T12:40:05.541Z",
    "status" : "Running",
    "errors" : [ ],
    "name" : "Parsing data as JSON",
    "processingStepType" : "ConvertToDomain"
  }, {
    "id" : "d529051d-c3de-4b2d-9b3b-d8d81f77551c",
    "endTime" : "2020-09-02T12:40:05.537Z",
    "status" : "Running",
    "errors" : [ ],
    "name" : "Retrieve data from S3",
    "processingStepType" : "RetrieveData"
  }, {
    "id" : "9005140d-dfea-4554-8018-ef57c29edd33",
    "endTime" : "2020-09-02T12:39:55.475022Z",
    "status" : "ShouldStart",
    "errors" : [ ],
    "name" : "Starting peterson/2020-09-02T12:26:47.585271Z.json",
    "processingStepType" : "Starting"
  }, {
    "id" : "90e66fcb-4be0-4d33-9ee6-60fe999904e5",
    "endTime" : "2020-09-02T12:26:47.708852Z",
    "status" : "ShouldStart",
    "errors" : [ ],
    "name" : "Starting peterson/2020-09-02T12:26:47.585271Z.json",
    "processingStepType" : "Starting"
  } ],
  "items" : [ ]
}
```

## Responses

| Key | Description |
|  --- | --- |
| 200 | Ok |
| 401 | *Unauthorized* Whenever you will get a 401 status, you have either provided the wrong credentials or none at all. Check if you bearer token has not expired |
| 403 | *Forbidden* You will receive this status, when you successfully supplied credentials, but your username does not have the necessary permissions for the resource |
| 404 | *Not Found* The requested planning was not found |