Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation: example response on API docs is not particularly informative #353

Open
jat255 opened this issue Nov 26, 2024 · 0 comments
Open

Comments

@jat255
Copy link
Member

jat255 commented Nov 26, 2024

In the context of #350, the pooch team requested a link to the API docs for their internal documentation (so they can refer to what responses to expect from various APIs). I noticed that the docs on https://data.nist.gov/rmm/#/operations/record, for instance, are not particularly informative when it comes to example responses:

{
  "empty": true,
  "property1": {},
  "property2": {}
}

When an actual response looks more like the data at the bottom of this post. It would be good if the auto-built API docs could have information about the full response to promote more interoperability.

{
  "_id": {
    "timestamp": 1727382918,
    "date": "2024-09-26T20:35:18.000+00:00"
  },
  "_schema": "https://data.nist.gov/od/dm/nerdm-schema/v0.7#",
  "@context": [
    "https://data.nist.gov/od/dm/nerdm-pub-context.jsonld",
    {
      "@base": "ark:/88434/mds2-3408"
    }
  ],
  "@type": [
    "nrdp:DataPublication",
    "nrdp:PublicDataResource",
    "dcat:Dataset"
  ],
  "_extensionSchemas": [
    "https://data.nist.gov/od/dm/nerdm-schema/pub/v0.7#/definitions/PublicDataResource"
  ],
  "@id": "ark:/88434/mds2-3408",
  "ediid": "ark:/88434/mds2-3408",
  "version": "1.0.1",
  "doi": "doi:10.18434/mds2-3408",
  "title": "Evaluation of static and dynamic magnetic properties of CoFeB versus thickness",
  "contactPoint": {
    "fn": "Hans Nembach",
    "hasEmail": "mailto:[email protected]"
  },
  "modified": "2024-07-12",
  "status": "available",
  "landingPage": "https://data.nist.gov/od/id/mds2-3408",
  "description": [
    "The enclosed dataset includes measurements of a thickness series of CoFeB thin film samples that were deposited at the NIST Magnetic Engineering Research Facility using magnetron sputtering. The thickness-dependent magnetic properties of CoFeB have significant technological relevance for predicting the read/write energy and speed of spin-transfer-torque magnetoresistive random access memory devices, which employ a nm-thick CoFeB film as the data storage layer. Ferromagnetic resonance observations were conducted using vector network analyzer ferromagnetic resonance  at fixed frequencies over a broad frequency range. The ferromagnetic resonance field and resonance linewidth versus frequency were used to determine the spectroscopic g-factor, effective magnetization Meff, Gilbert damping and the inhomogeneous linewidth broadening, respectively. This is a preliminary release and additional data will be added as this project continues"
  ],
  "keyword": [
    "ferromagnetic resonance",
    "MRAM",
    "magnetism",
    "ferromagnetism",
    "thin film"
  ],
  "topic": [
    {
      "@type": "Concept",
      "scheme": "https://data.nist.gov/od/dm/nist-themes/v1.1",
      "tag": "Physics: Magnetics"
    },
    {
      "@type": "Concept",
      "scheme": "https://data.nist.gov/od/dm/nist-themes/v1.1",
      "tag": "Nanotechnology"
    },
    {
      "scheme": "https://data.nist.gov/od/dm/nist-themes-chipsmetrology/v1.0",
      "tag": "Materials Research: Device Material: Sapphire",
      "@type": "Concept"
    },
    {
      "scheme": "https://data.nist.gov/od/dm/nist-themes-chipsmetrology/v1.0",
      "tag": "Materials Research: Device Material: Al2O3",
      "@type": "Concept"
    },
    {
      "scheme": "https://data.nist.gov/od/dm/nist-themes-chipsmetrology/v1.0",
      "tag": "Microelectronics: Magnetic Device: MRAM",
      "@type": "Concept"
    },
    {
      "scheme": "https://data.nist.gov/od/dm/nist-themes-chipsmetrology/v1.0",
      "tag": "Metrology: Measurement: Resonant Processes",
      "@type": "Concept"
    },
    {
      "scheme": "https://data.nist.gov/od/dm/nist-themes-chipsmetrology/v1.0",
      "tag": "Metrology: Grand Challenge: 4-Modeling and Simulating Semiconductor Materials, Designs, and Components",
      "@type": "Concept"
    }
  ],
  "accessLevel": "public",
  "license": "https://www.nist.gov/open/license",
  "publisher": {
    "name": "National Institute of Standards and Technology",
    "@type": "org:Organization"
  },
  "language": [
    "en"
  ],
  "bureauCode": [
    "006:55"
  ],
  "programCode": [
    "006:052"
  ],
  "theme": [
    "Physics:MagneticsNanotechnology"
  ],
  "_editStatus": "done",
  "components": [
    {
      "@id": "cmps/3408_README.txt",
      "@type": [
        "nrdp:DataFile",
        "nrdp:DownloadableFile",
        "dcat:Distribution"
      ],
      "_extensionSchemas": [
        "https://data.nist.gov/od/dm/nerdm-schema/pub/v0.7#/definitions/DataFile"
      ],
      "filepath": "3408_README.txt",
      "downloadURL": "https://data.nist.gov/od/ds/mds2-3408/3408_README.txt",
      "mediaType": "text/plain",
      "title": "3408_README",
      "size": 4603,
      "checksum": {
        "hash": "18561143afbbd2f7343de98214a1f1cccd21f790812ff3083c2e50bd568487ba",
        "algorithm": {
          "tag": "sha256",
          "@type": "Thing"
        }
      }
    },
    {
      "@id": "cmps/FMR%20Measurements",
      "@type": [
        "nrdp:Subcollection"
      ],
      "_extensionSchemas": [
        "https://data.nist.gov/od/dm/nerdm-schema/pub/v0.7#/definitions/Subcollection"
      ],
      "filepath": "FMR Measurements"
    },
    {
      "@id": "cmps/FMR Measurements/FMR fit functions.pdf",
      "@type": [
        "nrdp:DataFile",
        "nrdp:DownloadableFile",
        "dcat:Distribution"
      ],
      "_extensionSchemas": [
        "https://data.nist.gov/od/dm/nerdm-schema/pub/v0.7#/definitions/DataFile"
      ],
      "filepath": "FMR Measurements/FMR fit functions.pdf",
      "downloadURL": "https://data.nist.gov/od/ds/mds2-3408/FMR%20Measurements%2FFMR%20fit%20functions.pdf",
      "mediaType": "application/pdf",
      "title": "FMR Measurements/FMR fit functions",
      "size": 165556,
      "checksum": {
        "hash": "57c10997ea76108b2c3abb56815fae1306eb85adc029171d613c1dd4e59fc0e6",
        "algorithm": {
          "tag": "sha256",
          "@type": "Thing"
        }
      }
    },
    {
      "@id": "cmps/FMR%20Measurements/Out-of-plane",
      "@type": [
        "nrdp:Subcollection"
      ],
      "_extensionSchemas": [
        "https://data.nist.gov/od/dm/nerdm-schema/pub/v0.7#/definitions/Subcollection"
      ],
      "filepath": "FMR Measurements/Out-of-plane"
    },
    {
      "@id": "cmps/FMR Measurements/Out-of-plane/20240411C_OPP.zip",
      "@type": [
        "nrdp:DataFile",
        "nrdp:DownloadableFile",
        "dcat:Distribution"
      ],
      "_extensionSchemas": [
        "https://data.nist.gov/od/dm/nerdm-schema/pub/v0.7#/definitions/DataFile"
      ],
      "filepath": "FMR Measurements/Out-of-plane/20240411C_OPP.zip",
      "downloadURL": "https://data.nist.gov/od/ds/mds2-3408/FMR%20Measurements%2FOut-of-plane%2F20240411C_OPP.zip",
      "mediaType": "application/zip",
      "title": "FMR Measurements/Out-of-plane/20240411C_OPP",
      "size": 217838,
      "checksum": {
        "hash": "be00755c851a535ba4395e9f8611eec4ba53d434d1720f3e995ae7775cc31080",
        "algorithm": {
          "tag": "sha256",
          "@type": "Thing"
        }
      }
    },
    {
      "@id": "cmps/FMR Measurements/Out-of-plane/20240410C_OPP.zip",
      "@type": [
        "nrdp:DataFile",
        "nrdp:DownloadableFile",
        "dcat:Distribution"
      ],
      "_extensionSchemas": [
        "https://data.nist.gov/od/dm/nerdm-schema/pub/v0.7#/definitions/DataFile"
      ],
      "filepath": "FMR Measurements/Out-of-plane/20240410C_OPP.zip",
      "downloadURL": "https://data.nist.gov/od/ds/mds2-3408/FMR%20Measurements%2FOut-of-plane%2F20240410C_OPP.zip",
      "mediaType": "application/zip",
      "title": "FMR Measurements/Out-of-plane/20240410C_OPP",
      "size": 151232,
      "checksum": {
        "hash": "c3cbe3160e2bc671436be881d021811261f455253446bba6a76efa81ef59f3a2",
        "algorithm": {
          "tag": "sha256",
          "@type": "Thing"
        }
      }
    },
    {
      "@id": "cmps/FMR Measurements/Out-of-plane/20240415B_OPP.zip",
      "@type": [
        "nrdp:DataFile",
        "nrdp:DownloadableFile",
        "dcat:Distribution"
      ],
      "_extensionSchemas": [
        "https://data.nist.gov/od/dm/nerdm-schema/pub/v0.7#/definitions/DataFile"
      ],
      "filepath": "FMR Measurements/Out-of-plane/20240415B_OPP.zip",
      "downloadURL": "https://data.nist.gov/od/ds/mds2-3408/FMR%20Measurements%2FOut-of-plane%2F20240415B_OPP.zip",
      "mediaType": "application/zip",
      "title": "FMR Measurements/Out-of-plane/20240415B_OPP",
      "size": 336449,
      "checksum": {
        "hash": "0fff4e39dd2334860f8a7d4d33da54c7ba4d7c9f7310b02a3bee86dbeaf1e3ef",
        "algorithm": {
          "tag": "sha256",
          "@type": "Thing"
        }
      }
    },
    {
      "@id": "cmps/FMR Measurements/Out-of-plane/20240412B_OPP.zip",
      "@type": [
        "nrdp:DataFile",
        "nrdp:DownloadableFile",
        "dcat:Distribution"
      ],
      "_extensionSchemas": [
        "https://data.nist.gov/od/dm/nerdm-schema/pub/v0.7#/definitions/DataFile"
      ],
      "filepath": "FMR Measurements/Out-of-plane/20240412B_OPP.zip",
      "downloadURL": "https://data.nist.gov/od/ds/mds2-3408/FMR%20Measurements%2FOut-of-plane%2F20240412B_OPP.zip",
      "mediaType": "application/zip",
      "title": "FMR Measurements/Out-of-plane/20240412B_OPP",
      "size": 149565,
      "checksum": {
        "hash": "9a242f1911e0440a8f85d284bd31828936138458d524d31adf210f1c14696bc6",
        "algorithm": {
          "tag": "sha256",
          "@type": "Thing"
        }
      }
    },
    {
      "@id": "cmps/FMR Measurements/Out-of-plane/20240410D_OPP.zip",
      "@type": [
        "nrdp:DataFile",
        "nrdp:DownloadableFile",
        "dcat:Distribution"
      ],
      "_extensionSchemas": [
        "https://data.nist.gov/od/dm/nerdm-schema/pub/v0.7#/definitions/DataFile"
      ],
      "filepath": "FMR Measurements/Out-of-plane/20240410D_OPP.zip",
      "downloadURL": "https://data.nist.gov/od/ds/mds2-3408/FMR%20Measurements%2FOut-of-plane%2F20240410D_OPP.zip",
      "mediaType": "application/zip",
      "title": "FMR Measurements/Out-of-plane/20240410D_OPP",
      "size": 153345,
      "checksum": {
        "hash": "bf783ae5de959e18d1068be65b58ed0b431d063e7b61767e6f5cf914ef26b261",
        "algorithm": {
          "tag": "sha256",
          "@type": "Thing"
        }
      }
    },
    {
      "@id": "cmps/FMR Measurements/Out-of-plane/20240410A_OPP.zip",
      "@type": [
        "nrdp:DataFile",
        "nrdp:DownloadableFile",
        "dcat:Distribution"
      ],
      "_extensionSchemas": [
        "https://data.nist.gov/od/dm/nerdm-schema/pub/v0.7#/definitions/DataFile"
      ],
      "filepath": "FMR Measurements/Out-of-plane/20240410A_OPP.zip",
      "downloadURL": "https://data.nist.gov/od/ds/mds2-3408/FMR%20Measurements%2FOut-of-plane%2F20240410A_OPP.zip",
      "mediaType": "application/zip",
      "title": "FMR Measurements/Out-of-plane/20240410A_OPP",
      "size": 153070,
      "checksum": {
        "hash": "a8025a673816dff74263956f3ffee9cb6f7eb385dd58233dda5e8a0c7b64bcb5",
        "algorithm": {
          "tag": "sha256",
          "@type": "Thing"
        }
      }
    },
    {
      "@id": "cmps/FMR Measurements/Header for fit results.pdf",
      "@type": [
        "nrdp:DataFile",
        "nrdp:DownloadableFile",
        "dcat:Distribution"
      ],
      "_extensionSchemas": [
        "https://data.nist.gov/od/dm/nerdm-schema/pub/v0.7#/definitions/DataFile"
      ],
      "filepath": "FMR Measurements/Header for fit results.pdf",
      "downloadURL": "https://data.nist.gov/od/ds/mds2-3408/FMR%20Measurements%2FHeader%20for%20fit%20results.pdf",
      "mediaType": "application/pdf",
      "title": "FMR Measurements/Header for fit results",
      "size": 130014,
      "checksum": {
        "hash": "080bab40c65827463cc709e9fa4a6f6bb7f4cb243a0449193115428a1913257c",
        "algorithm": {
          "tag": "sha256",
          "@type": "Thing"
        }
      }
    },
    {
      "@id": "cmps/FMR Measurements/Header for Data.pdf",
      "@type": [
        "nrdp:DataFile",
        "nrdp:DownloadableFile",
        "dcat:Distribution"
      ],
      "_extensionSchemas": [
        "https://data.nist.gov/od/dm/nerdm-schema/pub/v0.7#/definitions/DataFile"
      ],
      "filepath": "FMR Measurements/Header for Data.pdf",
      "downloadURL": "https://data.nist.gov/od/ds/mds2-3408/FMR%20Measurements%2FHeader%20for%20Data.pdf",
      "mediaType": "application/pdf",
      "title": "FMR Measurements/Header for Data",
      "size": 87553,
      "checksum": {
        "hash": "f073122a484aa59e0c1a465d7f27c40cea7da1daf8cdd3b51059d63c8207286e",
        "algorithm": {
          "tag": "sha256",
          "@type": "Thing"
        }
      }
    }
  ],
  "authors": [
    {
      "familyName": "Nembach",
      "fn": "Hans  Nembach",
      "givenName": "Hans",
      "middleName": "",
      "affiliation": [
        {
          "title": "National Institute of Standards and Technology",
          "@type": "org:Organization",
          "@id": "ror:05xpvk416"
        }
      ],
      "orcid": "0000-0002-1676-0958",
      "@type": "foaf:Person"
    },
    {
      "familyName": "Gopman",
      "fn": "Daniel  Gopman",
      "givenName": "Daniel",
      "middleName": "",
      "affiliation": [
        {
          "title": "National Institute of Standards and Technology",
          "@type": "org:Organization",
          "@id": "ror:05xpvk416"
        }
      ],
      "orcid": "0000-0003-4172-8113",
      "@type": "foaf:Person"
    },
    {
      "familyName": "Pufall",
      "fn": "Matt  Pufall",
      "givenName": "Matt",
      "middleName": "",
      "affiliation": [
        {
          "title": "National Institute of Standards and Technology",
          "@type": "org:Organization",
          "@id": "ror:05xpvk416"
        }
      ],
      "orcid": "0000-0001-9530-0302",
      "@type": "foaf:Person"
    },
    {
      "familyName": "Shoup",
      "fn": "Jenae E Shoup",
      "givenName": "Jenae",
      "middleName": "E",
      "affiliation": [
        {
          "title": "National Institute of Standards and Technology",
          "@type": "org:Organization",
          "@id": "ror:05xpvk416"
        }
      ],
      "orcid": "0000-0001-7405-7809",
      "@type": "foaf:Person"
    },
    {
      "familyName": "Peria",
      "fn": "William Kenneth Peria",
      "givenName": "William",
      "middleName": "Kenneth",
      "affiliation": [
        {
          "title": "National Institute of Standards and Technology",
          "@type": "org:Organization",
          "@id": "ror:05xpvk416"
        }
      ],
      "orcid": "0000-0002-3520-5984",
      "@type": "foaf:Person"
    }
  ],
  "annotated": "2024-09-26T14:56:23.363066",
  "revised": "2024-09-26T14:36:33.503453",
  "issued": null,
  "firstIssued": "2024-09-26T14:36:33.503453",
  "releaseHistory": {
    "@id": "ark:/88434/mds2-3408/pdr:v",
    "@type": [
      "nrdr:ReleaseHistory"
    ],
    "hasRelease": [
      {
        "version": "1.0.0",
        "issued": "2024-07-12",
        "@id": "ark:/88434/mds2-3408.v1_0_0/pdr:v/1.0.0",
        "location": "https://data.nist.gov/od/id/ark:/88434/mds2-3408.v1_0_0/pdr:v/1.0.0",
        "description": "initial release"
      },
      {
        "version": "1.0.1",
        "issued": "2024-09-26",
        "@id": "ark:/88434/mds2-3408/pdr:v/1.0.1",
        "location": "https://data.nist.gov/od/id/ark:/88434/mds2-3408/pdr:v/1.0.1",
        "description": "add CHIPS METIS metadata"
      }
    ]
  },
  "versionHistory": [
    {
      "version": "1.0.1",
      "issued": "2024-09-26",
      "@id": "ark:/88434/mds2-3408",
      "location": "https://data.nist.gov/od/id/ark:/88434/mds2-3408",
      "description": "add CHIPS METIS metadata"
    }
  ],
  "isPartOf": [
    {
      "@type": [
        "nrda:ScienceTheme",
        "nrdp:PublicDataResource"
      ],
      "@id": "ark:/88434/pdr0-0002",
      "title": "CHIPS METIS Data"
    }
  ]
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant