Spacex-api: Upcoming breaking changes - v4.1.0

[jakewmeyer]

Intro

This is to provide some advanced warning for some breaking changes slated for v4.1.0

Currently all the breaking changes are in the /v4/launches endpoint, and are schema changes to support additional data going forward.

Changes

Launches - Fairings

Old format:

{
  "fairings": {
    "reused": false,
    "recovery_attempt": true,
    "recovered": true,
    "ships": [
      "5ea6ed2e080df4000697c908",
      "5ea6ed2f080df4000697c90c"
    ]
  }
}

This doesn't account for individual fairing half recoveries, or reuse tracking per half. Moving forward, fairings will be tracked in an endpoint similar to how cores, capsules, etc... are tracked currently.

New format:

{
  "fairings": [
    {
      "fairing": "5ea6ed30080df4000697c913",
      "flight": 3,
      "reused": true,
      "net_attempt": true,
      "net_landing": true,
      "water_attempt": false,
      "water_landing": false,
      "recovered": true,
      "ships": [
        "5ea6ed2f080df4000697c90d"
      ]
    },
    {
      "fairing": "6e46ed30080df4781697c913",
      "flight": 3,
      "reused": true,
      "net_attempt": true,
      "net_landing": true,
      "water_attempt": false,
      "water_landing": false,
      "recovered": true,
      "ships": [
        "5ea6ed30080df4000697c913"
      ]
    }
  ]
}

Launches - Crew

The current crew implementation doesn't allow for launch specific information like mission role, or other info that could vary from launch to launch.

Old format:

{
  "crew": [
    "5fe3c587b3467846b3242198",
    "5fe3c5beb3467846b3242199",
    "5fe3c5f6b3467846b324219a"
  ]
}

New format:

{
  "crew": [
    {
      "crew": "5fe3c587b3467846b3242198",
      "role": "Commander"
    },
    {
      "crew": "5fe3c5beb3467846b3242199",
      "role": "Pilot"
    },
    {
      "crew": "5fe3c5f6b3467846b324219a",
      "role": "Mission Specialist 1"
    }
  ]
}

[jesusrp98]

Is there an ETA for the implementation of this change?

[jakewmeyer]

Still need to gather + add all the fairing data, so it might be a few weeks. Once I have a concrete timeline, I'll tag a bunch of people, so there's plenty of warning.

[jakewmeyer]

TLDR: If you use any info about fairings or crew members within launches this change applies to you.

See the top of this issue for the new vs old formats for fairings and crew members within launches. At this point all the changes are live on https://stage.spacexdata.com/v4/launches. I'll let the changes stay there for a bit while people make any necessary updates to apps/sites/etc. After that we can set a date to migrate the changes to prod. Trying to make the process as smooth as possible.

@jesusrp98 @MattoDeg @PatrykWojcieszak @stanifert @Tearth @russelltwarwick @timisenman @jeroenboumans @DanielScholte

If I'm forgetting anyone, feel free to tag others

[Tearth]

Thank you, I will try to update my library soon. @AzuxDario, you should it read too.

[jesusrp98]

Great! I just need some clarification regarding fairing information @jakewmeyer

If there's no available data, like for example in future missions, the fairing object is empty (empty list). Is this intentional?
I think it would be better just adding the fairing object with null fields. This way, it would differ from Dragon launches, which definitely do not have fairings.

[jakewmeyer]

Was on the fence about that, but I think keeping the old behavior for dragon launches is more clear than an empty array. The states would look like the following:

1. State for all launches without fairings (including Dragon)

{
  "fairings": null
}

1. State for new launches with fairings, identical to how the cores array works.

{
  "fairings": [
    {
      "fairing": null,
      "flight": null,
      "reused": null,
      "net_attempt": null,
      "net_landing": null,
      "water_attempt": null,
      "water_landing": null,
      "recovered": null,
      "ships": []
    },
    {
      "fairing": null,
      "flight": null,
      "reused": null,
      "net_attempt": null,
      "net_landing": null,
      "water_attempt": null,
      "water_landing": null,
      "recovered": null,
      "ships": []
    }
  ]
}

[zacdevil10]

@jakewmeyer - Thanks for the update. Your first comment doesn't have "water_attempt" included for fairings. I assume this omission is a mistake.

Also when populating crew.crew on https://stage.spacexdata.com/v4/launches/query the launches are empty for the instances where they shouldn't be, is this expected behaviour on this url (everything else populates correctly so I would assume it isn't)?

[spacexdash]

@jakewmeyer

I am a bit confused - hoping you can clarify. Is the following a reasonable statement (net_landing || water_landing) == recovered?

Also say, net_attempt is true but it misses the net and ends up being a water landing. Would it read net_attempt = true, net_landing = false, water_attempt = false, water_landing = true?

[jakewmeyer]

@zacdevil10 Whoops, updated

[jakewmeyer]

@spacexdash In the specific cases you referenced:

1. Mostly a reasonable assumption, but in the past there were cases where a fairing landing in the ocean was so badly damaged they didn't bother recovering it, hence the separate recovered field.
2. Correct, water_attempt would only be true if it was a planned ocean landing from the beginning.

[jakewmeyer]

Here's some field explanations to clarify the meaning a bit better:

• ships contains the id's of ships involved in the recovery of that specific fairing half

| | True | False | Null |
|---------------|-----------------------------------------------------------|-----------------------------------------------------------------|-----------------------|
| Net Attempt | A ship attempted to catch the fairing with a net | No ship attempted a fairing catch with a net | Net attempt unknown |
| Net Landing | The fairing was caught in a net | The fairing was not caught in a net | Net landing unknown |
| Water Attempt | There was a planned ocean landing | There was not a planned ocean landing | Water attempt unknown |
| Water Landing | The fairing landed in the water during a planned recovery | The fairing did not land in the water during a planned recovery | Water landing unknown |
| Recovered | The fairing was recovered by a ship | The fairing was not recovered by a ship | Unknown if recovered |
| Reused | The fairing was used on a previous flight | The fairing is brand new | Unknown if reused |

[zacdevil10]

@jakewmeyer - The new response doesn't include a recovered field. Based on what you have just said shouldn't it?

[jakewmeyer]

@zacdevil10 Ah, we added that field in a separate issue, and somehow it didn't get added.

Stage is updated with _all_ the fields now 🙃

[spacexdash]

@jakewmeyer Thanks for the table this helps knowing it can be net_attempt but actually water_landing.

QQ now on how to determine if the faring destroyed itself. Would it just be the case that recovered is not null and is false?

EDIT - Ah nvm - pretty clear this is the case from the table

[jakewmeyer]

@spacexdash Yeah, if it wasn't recovered, in 100% of the cases it was destroyed beyond recovery.

[spacexdash]

@jakewmeyer Hey i noticed something in staging - sometimes the fairing id can be null despite flight being greater than 1. E.g. 5fb95b3f3a88ae63c954603c . Not particularly concerned for my use case but not sure if this is expected behaviour or not.

[jakewmeyer]

This is a bit of a weird one, so currently it's the solution.

In this case, SpaceX confirmed that the fairing was reused on a previous launch, but didn't specify which launch it was. So we could either guess which fairing half it was or leave it as null (unknown)

Unfortunately one of the issues of tracking every fairing half, there's not nearly as much info released on them.

[spacexdash]

@jakewmeyer thanks for clearing that up - makes complete sense!