CEDAR REST APIs

This page provides an informal guide to help you quickly get working with CEDAR REST APIs. For a broad overview of the APIs and quick access to their documentation, go here.

Getting a CEDAR API Key

First create an account on CEDAR at cedar.metadatacenter.net. Each registered user will be assigned an API key. For a research group it may make sense to create a central project user and use the user's API key for all CEDAR access.

To find this API key, log in to CEDAR at cedar.metadatacenter.net and click on the person icon on the top right of the desktop and select the 'Profile' option.

Note this API key. This key is needed for all CEDAR REST calls.

Format of CEDAR Repository Resources

CEDAR templates, elements, and fields are represented using JSON Schema. Instances are represented using JSON-LD.

The CEDAR Repository Model defines the representation of these entities. You can directly access any of these key documents: a paper describing this model; or, a full description of the model; or a description of the format of metadata instances in the CEDAR repository.

Note that you can also look at the JSON representing CEDAR resources by opening the resource in the CEDAR tool and clicking on the circle icons on the top right of the screen. (The left-hand icon shows template JSON, the right-hand icon shows instance JSON.) These will allow you to eyeball the representation of resources without going through the REST APIs.

Invoking the REST Endpoints

We've used Swagger to create our online REST API documentation](https://resource.metadatacenter.net/api ). The overall documentation of the user-facing services should be complete and fully accessible. (Click on a row topic to see all the API calls available for that topic; click on an individual call to see details about the call.)

You can try these endpoints interactively via the Swagger-generated pages, or you can use curl.

Here are some example curl commands you can try to retrieve templates and instances:

• Find all resources that match a search query. For q=* all resources will be retrieved.

   curl -H "Content-Type: application/json" -H "Authorization: apiKey <yourApiKey>" \
       -X GET "https://resource.metadatacenter.net/search?q=<searchQuery>"
  

This query will return all templates, elements, fields, instances or folders that match the query.

• To find all resources of a particular type use the resource_types parameter followed by one or more comma-separated types. Possible values are template, element, instance and folder.

   curl -H "Content-Type: application/json" -H "Authorization: apiKey <yourApiKey>" \
       -X GET "https://resource.metadatacenter.net/search?q=<searchQuery>&resource_types=<resourceTypes>"
  

• Retrieve all templates and elements:

   curl -H "Content-Type: application/json" -H "Authorization: apiKey <yourApiKey>" \
       -X GET "https://resource.metadatacenter.net/search?q=*&resource_types=template,element"
  

• To find all instances of a particular template use the template_id field to identify the template:

   curl -H "Content-Type: application/json" -H "Authorization: apiKey <yourApiKey>" \
       -X GET "https://resource.metadatacenter.net/search?template_id=<templateId>"
  

  Find all instances of the template with the ID https://repo.metadatacenter.net/templates/c1199f96-dbd3-4476-8141-1f1fb13e1bca:

   curl -H "Content-Type: application/json" -H "Authorization: apiKey <yourApiKey>" \
       -X GET "https://resource.metadatacenter.net/search?q=*&template_id=https://repo.metadatacenter.net/templates/c1199f96-dbd3-4476-8141-1f1fb13e1bca"
  

• Retrieve the content of a particular resource:

   curl -H "Content-Type: application/json" -H "Authorization: apiKey <yourApiKey>" \
       -X GET --header "Accept: application/json" "https://resource.metadatacenter.net/<resourceType>/<resourceId>"
  

  with:

  • <resourceType> = {templates|template_elements|template_instances}
  • <resourceId> is the resource identifier (@id field). Note that the resource identifier must be URL encoded (e.g., https%3A%2F%2Frepo.metadatacenter.net%2Ftemplate-instances%2F30e39969-1995-47c9-bb74-a086dddced8e).

• Retrieve the content of the template with the ID https://repo.metadatacenter.net/templates/c1199f96-dbd3-4476-8141-1f1fb13e1bca:

   curl -H "Content-Type: application/json" -H "Authorization: apiKey <yourApiKey>" \
       -X GET --header 'Accept: application/json' 
       'https://resource.metadatacenter.net/templates/https%3A%2F%2Frepo.metadatacenter.net%2Ftemplates%2Fc1199f96-dbd3-4476-8141-1f1fb13e1bca'
  

- Create a new resource:

	```
	curl -H "Content-Type: application/json" -H "Authorization: apiKey <yourApiKey>" \
        -X POST --data-binary @resource.json https://resource.metadatacenter.net/<resourceType>?folder_id=<folderId>
	```

	with:
    - \<resource.json> = JSON file with the resource (i.e., template, element, or instance) that will be created.
    - \<resourceType> = {templates|template-elements|template-instances}.
    - \<folderId> is the identifier of the folder that will contain the resource. It can be found on the CEDAR Workbench, as part of the URL. It must be encoded (e.g., https:%2F%2Frepo.metadatacenter.net%2Ffolders%2F23640714-f371-40f1-b2e6-ed2819ccc5e6). 

### Support

If you have questions about these APIs, please subscribe to the [CEDAR Users Support
mailing list](https://mailman.stanford.edu/mailman/listinfo/cedar-users).
After subscribing, send messages to `cedar-users` at `lists.stanford.edu`.