{"openapi":"3.1.0","info":{"title":"Atomio API","description":"API to Atomio syndication server enabling the creation an management of feeds and their contents.\n\n\nFeeds consist of zero or more entries, each entry can have one or more artefact. Artefacts are files and can be more or less anything.\n\n\nFeeds and entries are created using a JSON representation bespoke to Atomio (schema defined below), and feeds can be retrieved using Atom or that JSON format. An entry must be created with an artefact, and artefacts can be added to and deleted from an entry, although the last artefact for an entry can't be deleted. Multiple artefacts for an entry allows multiple forms of the same item to be hosted - for example a FHIR resource as JSON and XML.\n\n\nWith respect to authorisation, if security is enabled a user will require the permissions on the entry to be able to download an artefact. Provision for permissions on feeds to limit access to feeds based on permissions has been made but is not yet implemented.","version":"2.2.5"},"servers":[{"url":"https://synd.ontoserver.csiro.au","description":"Generated server url"}],"paths":{"/alias/{aliasName}":{"get":{"tags":["alias"],"summary":"Gets an alias as JSON indicating the alias name and the feed it points to","operationId":"getAlias","parameters":[{"name":"aliasName","in":"path","description":"Name of the alias to get","required":true,"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9-_]+$"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/Alias"}}}}}},"put":{"tags":["alias"],"summary":"Updates an alias to point at a different feed","operationId":"updateAlias","parameters":[{"name":"aliasName","in":"path","description":"Alias name to update - must match the passed Alias JSON object","required":true,"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9-_]+$"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Alias"}}},"required":true},"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/Alias"}}}}}},"delete":{"tags":["alias"],"summary":"Deletes an alias for a feed","description":"This operation deletes an alias for a feed - note this has no effect on the feed itself, just the alias.","operationId":"deleteAlias","parameters":[{"name":"aliasName","in":"path","description":"Name of the alias to delete","required":true,"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9-_]+$"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"type":"string"}}}}}}},"/feed":{"get":{"tags":["feed"],"summary":"Gets a list of feeds available on the server.","operationId":"listFeeds","responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"200":{"description":"List of feeds on the server","content":{"application/json":{"example":[{"name":"feed-name","title":"Title of the feed","url":"http://url.to/the/feed"}]}}}}},"post":{"tags":["feed"],"summary":"Create a new feed.","operationId":"createFeed","parameters":[{"name":"Accept","in":"header","required":false,"schema":{"type":"string","default":"application/atom+xml"}}],"requestBody":{"description":"Details of the Feed to be created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Feed"},"examples":{"An example request with the minimum required fields to create.":{"summary":"Minimal request","description":"An example request with the minimum required fields to create.","value":{"name":"test","title":"my test feed"}},"An example request with all fields provided with example values.":{"summary":"Full request","description":"An example request with all fields provided with example values.","value":{"name":"test","title":"my test feed","sub-title":"my subtitle"}}}}},"required":true},"responses":{"400":{"description":"Feed already exists","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"201":{"description":"Details of the created feed","content":{"application/json":{"example":{"name":"test","uuid":"d8ead610-d9a6-423a-9e40-48e2c748f049","title":"my test feed","subtitle":null,"published":"2020-12-02T04:36:22.697+00:00","updated":"2020-12-02T04:36:22.697+00:00","entries":[],"permissions":[]}}}}}}},"/feed/{feedName}/entry":{"post":{"tags":["entry"],"summary":"Creates an entry from specified metadata and a provided artefact.","description":"This request creates a new entry in a specified feed from supplied metadata and the artefact itself uploaded in a multipart form-data request.","operationId":"createEntry","parameters":[{"name":"feedName","in":"path","description":"The feed to add the entry to","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9-_]+$"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"entry":{"$ref":"#/components/schemas/Entry"},"file":{"type":"string","format":"binary","description":"The artefact for the entry"}},"required":["entry","file"]}}}},"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entry"}}}}}}},"/feed/{feedName}/entry/{entry}/artefact":{"post":{"tags":["artefact"],"summary":"Adds an artefact to an existing entry.","description":"An entry must have at least one artefact when it is created, but other artefacts can be added to an entry. This is used to provide the artefact in different formats, for example a FHIR resource can be added as a JSON artefact and an XML artefact. When specifying the Artefact metadata, type and filename are required, length and sha256 are not. If length and sha256 are supplied they will be checked against the uploaded content to confirm it is transferred unadulterated.","operationId":"addFileToEntry","parameters":[{"name":"feedName","in":"path","description":"Feed the entry to add the artefact is in","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9-_]+$"}},{"name":"entry","in":"path","description":"UUID of the entry to add the artefact to","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"artefact":{"$ref":"#/components/schemas/Artefact"},"file":{"type":"string","format":"binary"}},"required":["artefact","file"]}}}},"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Artefact"}}}}}}},"/feed/{feedName}/entry/$clone":{"post":{"tags":["entry"],"summary":"Clones an entry from another feed into the specified feed","operationId":"cloneEntry","parameters":[{"name":"feedName","in":"path","description":"Name of the feed to cone the entry into","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9-_]+$"}},{"name":"url","in":"query","description":"URL of the feed the entry to clone is in","required":true,"schema":{"type":"string"}},{"name":"entryId","in":"query","description":"Identifier of the entry to clone, in Atom this is a UUID","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"generateNewId","in":"query","description":"Whether to generate a new entry id for the cloned entry, or use the UUID of the entry being cloned","required":false,"schema":{"type":"boolean"}},{"name":"ignorePermissions","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"200":{"description":"The new entry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entry"}}}}}}},"/feed/$clone":{"post":{"tags":["feed"],"summary":"Clones the content of another feed.","description":"Used to clone the content of another feed, this request will attempt to create a new feed with the specified name and download and create entries for each of the entries in the target feed.","operationId":"cloneFeed","parameters":[{"name":"name","in":"query","description":"Name of the feed to create when cloning the target feed.","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9-_]+$"}},{"name":"url","in":"query","description":"URL of the feed to clone.","required":true,"schema":{"type":"string"}},{"name":"ignorePermissions","in":"query","description":"Boolean indicating whether permissions should be ignored.","required":false,"schema":{"type":"boolean"}},{"name":"Accept","in":"header","required":false,"schema":{"type":"string","default":"application/atom+xml"}}],"responses":{"400":{"description":"Feed already exists","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"201":{"description":"The new cloned feed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Feed"}},"application/atom+xml":{}}}}}},"/alias":{"get":{"tags":["alias"],"summary":"Gets all known aliases and their feed","operationId":"getAlias_1","responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Alias"}}}}}}},"post":{"tags":["alias"],"summary":"Adds an alias for a feed","description":"This operation adds an alias for a feed, which creates another URL the feed can be referenced by. Aliases can be moved, so an alias can represent a well known URL which can be moved to point at different feeds over time. Like a symlink.","operationId":"createAlias","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Alias"}}},"required":true},"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/Alias"}}}}}}},"/admin/validate-storage":{"post":{"tags":["administration"],"summary":"Runs self test on the artefacts stored in the server.","description":"This operation performs a test of all the artefacts referenced by the various entries and feeds in the server. It ensures that the artefacts are accessible and match the length and SHA256 hash stored for the artefacts to ensure there is no corruption. Typically this process is executed on a schedule in the background, however this request allows this self test to be requested on demand at any time.","operationId":"checkStorage","responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"200":{"description":"Response examples","content":{"application/json":{"examples":{"Validation passed":{"description":"Validation passed","value":{"failedPaths":{},"result":"OK"}},"Validation failed":{"description":"Validation failed","value":{"failedPaths":{"/path/to/file/with/issue":["Message explaining the problem","Message explaining another problem"],"/path/to/another/file/with/issue":["Message explaining the problem"]},"result":"FAILED"}}}}}}}}},"/feed/{feedName}":{"get":{"tags":["feed"],"summary":"Gets the content of the feed as a JSON object.","operationId":"getFeed","parameters":[{"name":"feedName","in":"path","description":"Name of the feed to get.","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9-_]+$"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"200":{"description":"The requested feed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Feed"}}}},"404":{"description":"The feed with the name requested does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Feed"}}}}}},"delete":{"tags":["feed"],"summary":"Deletes the specified feed.","operationId":"deleteFeed","parameters":[{"name":"feedName","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9-_]+$"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"type":"string"}}}}}},"patch":{"tags":["feed"],"summary":"Edit the contents of a feed.","operationId":"editFeed","parameters":[{"name":"feedName","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9-_]+$"}},{"name":"Accept","in":"header","required":false,"schema":{"type":"string","default":"application/atom+xml"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedPatch"}}},"required":true},"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"204":{"description":"Parts of the feed to update.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Feed"}},"application/xml":{}}}}}},"/feed/{feedName}/entry/{entry}":{"delete":{"tags":["entry"],"summary":"Deletes an entry from a specified feed","description":"This will delete an entry from a feed, but an entry may appear in multiple feeds and this operation won't affect those feeds. If as a result of deleting this entry any of the artefacts (files on disk) that the entry references are no longer referenced by any entries, those artefacts will be removed from disk to clean up storage.","operationId":"deleteEntry","parameters":[{"name":"feedName","in":"path","description":"Feed to delete the entry from","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9-_]+$"}},{"name":"entry","in":"path","description":"Entry to delete","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"type":"string"}}}}}},"patch":{"tags":["entry"],"summary":"Edit the contents of an entry.","operationId":"editEntry","parameters":[{"name":"feedName","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9-_]+$"}},{"name":"entry","in":"path","description":"UUID of the entry the artefact is in","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Accept","in":"header","required":false,"schema":{"type":"string","default":"application/atom+xml"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntryPatch"}}},"required":true},"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"200":{"description":"Parts of the entry to update.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entry"}}}}}}},"/feed/{feedName}/syndication.xml":{"get":{"tags":["feed"],"summary":"Gets the content of the feed as an Atom XML feed.","operationId":"getFeedAsAtom","parameters":[{"name":"feedName","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9-_]+$"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"200":{"description":"The requested feed.","content":{"application/atom+xml":{}}},"404":{"description":"The feed with the name requested does not exist.","content":{"application/atom+xml;charset=UTF-8":{"schema":{"type":"string"}}}}}}},"/feed/{feedName}/entry/{entry}/artefact/{fileName}":{"get":{"tags":["artefact"],"summary":"Gets an artefact","description":"Streams the artefact data with a content disposition including the filename.","operationId":"getEntryFile","parameters":[{"name":"feedName","in":"path","description":"Name of the feed the entry/artefact is in","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9-_]+$"}},{"name":"entry","in":"path","description":"UUID of the entry the artefact is in","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"fileName","in":"path","description":"The filename of the file artefact in the entry","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9-_]+[A-Za-z0-9-_.]*$"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"type":"string","format":"binary"}}}}}},"delete":{"tags":["artefact"],"summary":"Deletes an artefact from an entry.","description":"This request deletes an artefact from an entry. If the artefact is also associated with other entries (possibly in other feeds) the artefact itself will not be deleted from disk. If the artefact file is no longer referenced by any entries after this operation, it will be deleted from disk to clean up diskspace.","operationId":"deleteEntryArtefact","parameters":[{"name":"feedName","in":"path","description":"Feed to delete the artefact from","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9-_]+$"}},{"name":"entry","in":"path","description":"UUID of the entry in the feed that contains the artefact to delete","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"fileName","in":"path","description":"Name of the file in the specified entry to delete","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9-_]+[A-Za-z0-9-_.]*$"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"type":"string"}}}}}}},"/feed/query":{"get":{"tags":["feed"],"summary":"Constructs an aggregate feed based on the request.","operationId":"queryBasedFeed","parameters":[{"name":"_include","in":"query","required":false,"schema":{"type":"string"}},{"name":"_exclude","in":"query","required":false,"schema":{"type":"string"}},{"name":"Accept","in":"header","required":false,"schema":{"type":"string","default":"application/atom+xml"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"200":{"description":"Query-based feed response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Feed"}}}}}}},"/alias/{aliasName}/syndication.xml":{"get":{"tags":["alias"],"summary":"Gets the content of the feed the alias is pointing to as an Atom XML feed.","operationId":"getAliasAsAtom","parameters":[{"name":"aliasName","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9-_]+$"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"200":{"description":"The requested feed.","content":{"application/atom+xml":{}}},"404":{"description":"The feed with the name requested does not exist.","content":{"application/atom+xml;charset=UTF-8":{"schema":{"type":"string"}}}}}}},"/":{"get":{"tags":["atomio-api"],"operationId":"redirectToLaunch","responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"type":"object"}}}}}}},"/.well-known/openid-configuration":{"get":{"tags":["atomio-api"],"operationId":"getSmartConfig","responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/.well-known/smart-configuration":{"get":{"tags":["atomio-api"],"operationId":"getSmartConfig_1","responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"Alias":{"type":"object","properties":{"name":{"type":"string","maxLength":30,"minLength":0,"pattern":"^[A-Za-z0-9-_]+$"},"feed":{"$ref":"#/components/schemas/Feed"},"published":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"}},"required":["feed","name"]},"Artefact":{"type":"object","properties":{"type":{"type":"string","maxLength":127,"minLength":0},"sha256":{"type":"string","maxLength":64,"minLength":0},"length":{"type":"integer","format":"int64"},"filename":{"type":"string","maxLength":255,"minLength":0},"validated":{"type":"boolean"}}},"Author":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"email":{"type":"string"}}},"Category":{"type":"object","properties":{"name":{"type":"string","minLength":1},"scheme":{"type":"string","minLength":1},"label":{"type":"string"}},"required":["name","scheme"]},"Entry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"authors":{"type":"array","items":{"$ref":"#/components/schemas/Author"}},"rights":{"type":"string"},"published":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"},"summary":{"type":"string"},"contentItemIdentifier":{"type":"string","minLength":1},"contentItemVersion":{"type":"string","minLength":1},"batchBundleInterpretation":{"type":"boolean"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"},"uniqueItems":true},"fhirVersion":{"type":"string"},"fhirProfiles":{"type":"array","items":{"type":"string"},"uniqueItems":true},"artefacts":{"type":"array","items":{"$ref":"#/components/schemas/Artefact"},"maxItems":2147483647,"minItems":1},"permissions":{"type":"array","items":{"type":"string"},"uniqueItems":true}},"required":["contentItemIdentifier","contentItemVersion"]},"Feed":{"type":"object","properties":{"name":{"type":"string","maxLength":30,"minLength":0,"pattern":"^[A-Za-z0-9-_]+$"},"uuid":{"type":"string","format":"uuid"},"title":{"type":"string","maxLength":255,"minLength":0},"subtitle":{"type":"string","maxLength":510,"minLength":0},"published":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"},"entries":{"type":"array","items":{"$ref":"#/components/schemas/Entry"}},"permissions":{"type":"array","items":{"type":"string"},"uniqueItems":true},"aliases":{"type":"array","items":{"$ref":"#/components/schemas/Alias"},"uniqueItems":true}},"required":["name","title"]},"FeedPatch":{"type":"object","properties":{"title":{"type":"string"},"subtitle":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"},"uniqueItems":true}}},"EntryPatch":{"type":"object","properties":{"title":{"type":"string"},"authors":{"type":"array","items":{"$ref":"#/components/schemas/Author"}},"rights":{"type":"string"},"summary":{"type":"string"},"batchBundleInterpretation":{"type":"boolean"},"fhirVersion":{"type":"string"},"fhirProfiles":{"type":"array","items":{"type":"string"},"uniqueItems":true},"permissions":{"type":"array","items":{"type":"string"},"uniqueItems":true}}}}}}