Skip to content

Latest commit

 

History

History
114 lines (78 loc) · 4.18 KB

DrupalRestAPI.md

File metadata and controls

114 lines (78 loc) · 4.18 KB
Raw

Documentation of the REST-API provided by DIPAS

Calling the endpoints

Generally all REST-endpoints are available at URL [server.tld[:port]]/drupal/dipas/[endpoint]. The service Drupal\dipas\Service\RestApi::requestEndpoint is responsible for the instantiation and the call of the plugins. The endpoint's answer will be cached context sensitively including potential GET-parameter. That means /drupal/dipas/contributionlist?page=1 has another cache than /drupal/dipas/contributionlist?page=2. To avoid the cache (e.g. due to development purposes) the GET-parameter noCache can be added to the Endpoint-URL (e.g. /drupal/dipas/contributionlist?page=2&noCache)

Development of (new) endpoints

All endpoints are delivered via PHP-plugin. These are located at /drupal/modules/custom/dipas/src/Plugin/ResponseKey. Plugins must implement the interface Drupal\dipas\PluginSystem\ResponseKeyPluginInterface and can extend Drupal\dipas\Plugin\ResponseKeyBase. The attribute id in the annotation of the plugin is essential for the URL path.

Plugins can restrict the allowed request methods (GET / POST/ ...). When the endpoint is called with a forbidden method, the server will return HTTP/404.

Available endpoints

See files in /drupal/modules/custom/dipas/src/Plugin/ResponseKey that do not have "Interface", "Base" or "Trait" in their name. The corresponding endpoints can be found as attribute id in the annotations of the file (comment area above the class defintion).

Available GET-parameters

  • in all endpoints:

    • noCache

      suppresses the loading and delivery of a cache of the endpoint (will regenerate the caches)

  • Endpoint contributionlist

    • itemsPerPage: Default 10. When -1 or 0 is given, no pagination will be applied.
    • page: single, specific page of the pager. If there are e.g. 33 contributions available and ?page=2 is called, contributions 11-20 will be shown

Required parameters

  • Endpoint contributiondetails:

    URL: /drupal/dipas/contributiondetails/[id]

    • id: type int

    Example: /drupal/dipas/contributiondetails/12

    Answer of the server:

    • in case of success the data object of the contribution
    • in case of error an array wit status "error" and the error message

  • Endpoint getcomments:

    URL: /drupal/dipas/getcomments/[id]

    • id: type int

    Example: /drupal/dipas/getcomments/12

    Answer of the server:

    • in case of success the data object with comments of the node
    • in case of error an array wit status "error" and the error message

  • Endpoint addcontribution:

    Required POST-fields: title: type string text: type string category: type int rubric: type int lat: type float (if mandatory depends on the configuration) lon: type float (if mandatory depends on the configuration) user: type int (if mandatory depends on the configuration)

    Answer of the server in case of success: nid: type int, node-ID of the newly created node

  • Endpoint addcomment:

    Required POST-fields: rootEntityID: type int (ID of the contribution node) commentedEntityType: type string (node or comment) commentedEntityID: type int subject: type string (at least an empty string) comment: type string

    Answer of the server:

    • in case of success the complete comment array as in endpoint getcomments
    • in case of error an array wit status "error" and the error message

  • Endpoint rate:

    URL: /drupal/dipas/rate/[id]

    • id: type int

    Example: /drupal/dipas/rate/12

    Required POST-fields:

    • rating: type int (1 for upvote, -1 for downvote)

    Available POST-fields:

    • entity_type: type string (entity type of the rated entity (default: "node"))

    Answer of the server:

    • in case of success the data object with current rating values
    • in case of error an array wit status "error" and the error message

  • Endpoint confirmcookies:

    Required POST-fields:

    • confirmCookies: type bool

    Answer of the server:

    • in case of success a data object with message that cookies were activated (status: success)
    • in case of error a data object with message that the cookie has not been activated (status: error)