egroupware/doc/REST-CalDAV-CardDAV/Links-and-attachments.md

EGroupware REST API for Links and attachments

• linking application entries to other application entries
• attaching files to application entries
• listing, creating and deleting links and attachments

Authentication is via Basic Auth with username and a password, or a token valid for:

• either just the given user or all users
• CalDAV/CardDAV Sync (REST API)
• application the link or attachment is created for

Following schema is used for JSON encoding of links and attachments

• @type: Link
• href: string URI to linked entry or attachments
• title: string title of link
• contentType: string application/json for links, content-type of attachments
• size: size of attachments
• egroupware.org-remark: string
• egroupware.org-app: string application name of the linked entry
• egroupware.org-id: string application ID of the linked entry
• rel: string egroupware.org-primary to mark a primary link for InfoLog entries

Supported request methods and examples

• GET to application entry collections to return all links and attachments

Example: Getting all links and attachments of a given application entry

curl https://example.org/egroupware/groupdav.php/<username>/<app>/<id>/links/ -H "Accept: application/pretty+json" --user <username>
HTTP/1.1 200 Ok
Content-Type: application/json

{
    "responses": {
        "/<username>/<app>/<id>/links/<link-id>": {
            "@type": "Link",
            "href": "https://example.org/egroupware/groupdav.php/ralf/addressbook/46",
            "contentType": "application/json",
            "title": "EGroupware GmbH: Becker, Ralf",
            "egroupware.org-app": "addressbook",
            "egroupware.org-id": "46",
            "egroupware.org-remark": "Testing ;)"
        },
        "/<username>/<app>/<id>/links/<link-id>": {
            "@type": "Link",
            "href": "https://example.org/egroupware/groupdav.php/ralf/infolog/1161",
            "contentType": "application/json",
            "title": "Test mit primärem Link (#1161)",
            "egroupware.org-app": "infolog",
            "egroupware.org-id": "1161"
        },
        "/<username>/<app>/<id>/links/<attachment-id>": {
            "@type": "Link",
            "href": "https://example.org/egroupware/webdav.php/apps/timesheet/199/image.svg",
            "contentType": "image/svg+xml",
            "size": 17167,
            "title": "image.svg"
        }
    }
}

• POST request to upload an attachment or link with another application entry

Example: Adding a PDF as attachment to an application entry

curl -i 'https://example.org/egroupware/groupdav.php/<username>/<app>/<id>/links/<filename>' -H "Content-Type: application/pdf" --data-binary @<path-to-pdf> --user <username>

HTTP/1.1 204 Created
Location: https://example.org/egroupware/groupdav.php/<username>/<app>/<id>/links/<attachment-id>

Example: Creating a link from one application entry to another

curl -i 'https://example.org/egroupware/groupdav.php/<username>/<app>/<id>/links/' -H "Content-Type: application/json" --data-binary @- --user <username> <<<EOF
{"app":"<2nd-app>","id":<2nd-app-id>,"remark":"This is a test ;)"}
EOF

HTTP/1.1 204 Created
Location: https://example.org/egroupware/groupdav.php/<username>/<app>/<id>/links/<link-id>

Example: Creating the primary link for an InfoLog entry

curl -i 'https://example.org/egroupware/groupdav.php/<username>/infolog/<id>/links/' -H "Content-Type: application/json" --data-binary @- --user <username> <<<EOF
{"app":"<2nd-app>","id":<2nd-app-id>,"rel":"egroupware.org-primary"}
EOF

HTTP/1.1 204 Created
Location: https://example.org/egroupware/groupdav.php/<username>/infolog/<id>/links/<link-id>

<id> is the numerical ID of the entry of application <app>, NOT the UUID some applications have! <2nd-app-id> is also the numerical ID of <2nd-app>, not the UUID

• DELETE request to remove a link or attachment

Example: deleting an attachment or link

curl -X DELETE 'https://example.org/egroupware/groupdav.php/<app>/<id>/links/<link-or-attachment-id>' --user <username>

HTTP/1.1 201 No Content

one can use Accept: application/pretty+json to receive pretty-printed JSON eg. for debugging and exploring the API