diff --git a/schemas/fcmaterials_capi-README.md b/schemas/fcmaterials_capi-README.md index 357da91..a76f136 100644 --- a/schemas/fcmaterials_capi-README.md +++ b/schemas/fcmaterials_capi-README.md @@ -1,8 +1,8 @@ # EDDN FCMaterials Schema ## Introduction -This is the documentation for how to take data from an ED `FCMaterials.json` -file and properly structure it for sending to EDDN. +This is the documentation for how to take data from an the ED CAPI `/market` +endpoint and properly structure it for sending to EDDN. Please consult [EDDN Schemas README](./README-EDDN-schemas.md) for general documentation for a schema such as this. @@ -16,23 +16,63 @@ to report any such anomalies you find so that we can check and resolve the discrepancy.** ## Senders -The data source for this schema is the file `FCMaterials.json`. That it has -been freshly written is signalled by the ED Journal event `FCMaterials`. -**NB: This schema is not, currently, for sending CAPI `/market`-sourced data -about these materials.** +The data source for this schema is the `/market` ED CAPI endpoint. You only +want selected parts of the full data returned for this schema. -So, monitor the Journal as normal, and when you see a `FCMaterials` event open -the `FCMaterials.json` file for reading, read it, and close it again. Use the -data you got from reading this file, not merely the Journal event. +You **MUST NOT** construct the message by starting with the entirety of the +CAPI data and then removing everything but what you need. That risks Frontier +adding more data to the endpoint and your `fcmaterials_capi` messages being +rejected as invalid. Instead, construct the message content by setting just +the data that is necessary. -Your `message` should primarily be the contents of this file, with the addition -of any augmentations, as noted below. +Your `message` object **MUST**: +1. Have an `"event":"FCMaterials"` member to aid Listeners who pass this + through a "usually from the Journal" code path. +2. Set a `"MarketID"` key with the value from `"id"` in the CAPI data. +3. Set a `"CarrierID"` key with the value from the `"name"` in the CAPI data. +4. Set the `"Items"` key's contents directly from the `/market` -> `orders` + -> `onfootmicroresources` CAPI data. +5. Remove any data where the key is `"locName"` from the `"Items"` data. + +You **MUST NOT**: +1. Attempt to set a `"CarrierName"` from any source, the `CarrierID` is + sufficient. + +### Example algorithm + +1. Make a CAPI `/market` query. +2. Set `event`, `MarketID` and `CarrierID` as outlined above. +3. Set `Items` value to the data in `orders.onfootmicroresources`. +4. Process the contents of `Items`, removing any data with a key of `locName`. ### Augmentations #### horizons and odyssey flags Please read [horizons and odyssey flags](../docs/Developers.md#horizons-and-odyssey-flags) in the Developers' documentation. +You **SHOULD** set these flags from the Journal `FileHeader` data if you are +reasonably sure you have a live game session against which you are performing +CAPI queries. +You **MUST NOT** set them otherwise, as e.g. the player could be active in +the game on another computer, using a different game mode and the CAPI data +will be for that game mode. + ## Listeners The advice above for [Senders](#senders), combined with the actual Schema file *should* provide all the information you need to process these events. + +Do note that the data source for this is the CAPI, and as such the data is not +the same as for the `fcmaterials_journal` schema: + +1. There is no good source of `CarrierName` in CAPI `/market` endpoint data, so + that is not included. +2. The `sales` and `purchases` values do **not** contain the same form of data. +3. The `sales` member of `Items` will be `[]` if there are no sales orders, but + when there are orders: + 1. It will be an object/dictionary. + 2. The keys are the commodity ID. + 3. The value of that key is the rest of the data for that sales order. +4. The `purchases` value: + 1. Is always an array, unlike `sales`. + 2. As a consequence does **not** provide the commodity id at all, only + the name.