Creating a Data Resource

The following example shows the creation of the first resource only providing mandatory fields:

$ curl 'http://localhost:8080/api/v1/dataresources/' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "id" : null,
  "identifier" : null,
  "creators" : [ {
    "id" : null,
    "familyName" : "Doe",
    "givenName" : "John",
    "affiliations" : [ "Karlsruhe Institute of Technology" ]
  } ],
  "titles" : [ {
    "id" : null,
    "value" : "Most basic resource for testing",
    "titleType" : "OTHER",
    "lang" : null
  } ],
  "publisher" : null,
  "publicationYear" : null,
  "resourceType" : {
    "id" : null,
    "value" : "testingSample",
    "typeGeneral" : "DATASET"
  },
  "subjects" : [ ],
  "contributors" : [ ],
  "dates" : [ ],
  "relatedIdentifiers" : [ ],
  "descriptions" : [ ],
  "geoLocations" : [ ],
  "language" : null,
  "alternateIdentifiers" : [ ],
  "sizes" : [ ],
  "formats" : [ ],
  "version" : null,
  "rights" : [ ],
  "fundingReferences" : [ ],
  "lastUpdate" : null,
  "state" : null,
  "embargoDate" : null,
  "acls" : [ ]
}'

You can see, that most of the sent document is empty. Only title, creator and resourceType are provided by the user. HTTP-wise the call looks as follows:

POST /api/v1/dataresources/ HTTP/1.1
Content-Type: application/json
Content-Length: 900
Host: localhost:8080

{
  "id" : null,
  "identifier" : null,
  "creators" : [ {
    "id" : null,
    "familyName" : "Doe",
    "givenName" : "John",
    "affiliations" : [ "Karlsruhe Institute of Technology" ]
  } ],
  "titles" : [ {
    "id" : null,
    "value" : "Most basic resource for testing",
    "titleType" : "OTHER",
    "lang" : null
  } ],
  "publisher" : null,
  "publicationYear" : null,
  "resourceType" : {
    "id" : null,
    "value" : "testingSample",
    "typeGeneral" : "DATASET"
  },
  "subjects" : [ ],
  "contributors" : [ ],
  "dates" : [ ],
  "relatedIdentifiers" : [ ],
  "descriptions" : [ ],
  "geoLocations" : [ ],
  "language" : null,
  "alternateIdentifiers" : [ ],
  "sizes" : [ ],
  "formats" : [ ],
  "version" : null,
  "rights" : [ ],
  "fundingReferences" : [ ],
  "lastUpdate" : null,
  "state" : null,
  "embargoDate" : null,
  "acls" : [ ]
}

As Content-Type only ‘application/json’ is supported and should be provided. The two other headers are typically set by the HTTP client. After validating the provided document, adding missing information where possible and persisting the created resource, the result is sent back to the user and will look that way:

HTTP/1.1 201 Created
Location: http://localhost:8080/api/v1/dataresources/edbf964c-f215-4fc6-9ef1-2ff1ea5a811e?version=1
ETag: "1543949803"
Resource-Version: 1
Content-Type: application/json
Content-Length: 1002

{
  "id" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e",
  "identifier" : {
    "id" : 1,
    "value" : "(:tba)",
    "identifierType" : "DOI"
  },
  "creators" : [ {
    "id" : 1,
    "familyName" : "Doe",
    "givenName" : "John",
    "affiliations" : [ "Karlsruhe Institute of Technology" ]
  } ],
  "titles" : [ {
    "id" : 1,
    "value" : "Most basic resource for testing",
    "titleType" : "OTHER"
  } ],
  "publisher" : "SELF",
  "publicationYear" : "2022",
  "resourceType" : {
    "id" : 1,
    "value" : "testingSample",
    "typeGeneral" : "DATASET"
  },
  "dates" : [ {
    "id" : 1,
    "value" : "2022-03-25T12:47:06Z",
    "type" : "CREATED"
  } ],
  "alternateIdentifiers" : [ {
    "id" : 1,
    "value" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e",
    "identifierType" : "INTERNAL"
  } ],
  "lastUpdate" : "2022-03-25T12:47:06.093Z",
  "state" : "VOLATILE",
  "acls" : [ {
    "id" : 1,
    "sid" : "SELF",
    "permission" : "ADMINISTRATE"
  } ]
}

What you see is, that the result looks different from the original document. A few elements, e.g. identifier, alternateIdentifiers, publisher, publicationYear, dates, acls and state received a value by the server. Furthermore, you’ll find an ETag header with the current ETag of the resource. This value is returned by POST, GET, PUT and PATCH calls and must be provided for all calls modifying the resource, e.g. PATCH, PUT and DELETE, in order to avoid conflicts.