[Pkg-owncloud-commits] [owncloud-doc] 54/270: move ocs to core dev, highlight deprecated info.xml entries
David Prévot
taffit at moszumanska.debian.org
Thu Jul 31 03:53:00 UTC 2014
This is an automated email from the git hooks/post-receive script.
taffit pushed a commit to branch master
in repository owncloud-doc.
commit c1f992d77aac72fb8e535d22d0830bbf5145ea6c
Author: Bernhard Posselt <dev at bernhard-posselt.com>
Date: Sun May 11 12:10:33 2014 +0200
move ocs to core dev, highlight deprecated info.xml entries
---
developer_manual/app/info.rst | 58 ++++++++++++++++++++-
developer_manual/core/externalapi.rst | 95 +++++++++++++++++++++++++++++++++++
developer_manual/core/index.rst | 2 +
3 files changed, 153 insertions(+), 2 deletions(-)
diff --git a/developer_manual/app/info.rst b/developer_manual/app/info.rst
index c6958d2..0a58efd 100644
--- a/developer_manual/app/info.rst
+++ b/developer_manual/app/info.rst
@@ -1,3 +1,4 @@
+============
App Metadata
============
@@ -12,21 +13,36 @@ The :file:`appinfo/info.xml` contains metadata about the app:
<id>yourappname</id>
<name>Your App</name>
<description>Your App description</description>
- <version>0.0.1</version>
+ <version>1.0</version>
<licence>AGPL</licence>
<author>Your Name</author>
- <require>7</require>
+ <require>5</require>
<types>
<type>filesystem</type>
</types>
+
<documentation>
<user>http://doc.owncloud.org</user>
<admin>http://doc.owncloud.org</admin>
</documentation>
<website>http://www.owncloud.org</website>
+
+ <!-- deprecated -->
+ <public>
+ <file id="caldav">appinfo/caldav.php</file>
+ </public>
+
+ <remote>
+ <file id="caldav">appinfo/caldav.php</file>
+ </remote>
+
+ <standalone />
+
+ <default_enable />
+ <shipped>true</shipped>
</info>
id
@@ -82,3 +98,41 @@ website
-------
link to project webpage
+Depcrecated
+===========
+
+The following sections are just listed for reference and should not be use because
+
+* **public/remote**: Use :doc:`api` instead because you'll have to use :doc:`../core/externalapi` which is known to be buggy (works only properly with GET/POST)
+* **standalone/default_enable**: They tell core what do on setup, you will not be able to even activate your app if it has those entries. This should be replaced by a config file inside core.
+
+public
+------
+Used to provide a public interface (requires no login) for the app. The id is appended to the URL **/owncloud/index.php/public**. Example with id set to 'calendar'::
+
+ /owncloud/index.php/public/calendar
+
+Also take a look at :doc:`../core/externalapi`.
+
+remote
+------
+Same as public but requires login. The id is appended to the URL **/owncloud/index.php/remote**. Example with id set to 'calendar'::
+
+ /owncloud/index.php/remote/calendar
+
+Also take a look at :doc:`../core/externalapi`.
+
+
+standalone
+----------
+Can be set to true to indicate that this app is a webapp. This can be used to tell GNOME Web for instance to treat this like a native application.
+
+default_enable
+--------------
+**Core apps only**: Used to tell ownCloud to enable them after the installation.
+
+shipped
+-------
+**Core apps only**: Used to tell ownCloud that the app is in the standard release.
+
+Please note that if this attribute is set to *FALSE* or not set at all, every time you disable the application, all the files of the application itself will be *REMOVED* from the server!
diff --git a/developer_manual/core/externalapi.rst b/developer_manual/core/externalapi.rst
new file mode 100644
index 0000000..04c05ca
--- /dev/null
+++ b/developer_manual/core/externalapi.rst
@@ -0,0 +1,95 @@
+External API
+============
+
+.. sectionauthor:: Tom Needham <tom at owncloud.com>
+
+Introduction
+------------
+The external API inside ownCloud allows third party developers to access data
+provided by ownCloud apps. ownCloud version 5.0 will follow the `OCS v1.7
+specification <http://www.freedesktop.org/wiki/Specifications/open-collaboration-services-1.7>`_ (draft).
+
+Usage
+-----
+
+Registering Methods
+~~~~~~~~~~~~~~~~~~~
+Methods are registered inside the :file:`appinfo/routes.php` using :php:class:`OCP\\API`
+
+.. code-block:: php
+
+ <?php
+
+ \OCP\API::register(
+ 'get',
+ '/apps/yourapp/url',
+ function($urlParameters) {
+ return new \OC_OCS_Result($data);
+ },
+ 'yourapp',
+ \OC_API::ADMIN_AUTH
+ );
+
+Returning Data
+~~~~~~~~~~~~~~
+Once the API backend has matched your URL, your callable function as defined in
+**$action** will be executed. This method is passed as array of parameters that you defined in **$url**. To return data back the the client, you should return an instance of :php:class:`OC_OCS_Result`. The API backend will then use this to construct the XML or JSON response.
+
+Authentication & Basics
+~~~~~~~~~~~~~~~~~~~~~~~
+Because REST is stateless you have to send user and password each time you access the API. Therefore running ownCloud **with SSL is highly recommended** otherwise **everyone in your network can log your credentials**::
+
+ https://user:password@yourowncloud.com/ocs/v1.php/apps/yourapp
+
+
+Output
+~~~~~~
+The output defaults to XML. If you want to get JSON append this to the URL::
+
+ ?format=json
+
+Output from the application is wrapped inside a **data** element:
+
+**XML**:
+
+.. code-block:: xml
+
+ <?xml version="1.0"?>
+ <ocs>
+ <meta>
+ <status>ok</status>
+ <statuscode>100</statuscode>
+ <message/>
+ </meta>
+ <data>
+ <!-- data here -->
+ </data>
+ </ocs>
+
+
+**JSON**:
+
+.. code-block:: js
+
+ {
+ "ocs": {
+ "meta": {
+ "status": "ok",
+ "statuscode": 100,
+ "message": null
+ },
+ "data": {
+ // data here
+ }
+ }
+ }
+
+Statuscodes
+~~~~~~~~~~~
+The statuscode can be any of the following numbers:
+
+* **100** - successfull
+* **996** - server error
+* **997** - not authorized
+* **998** - not found
+* **999** - unknown error
\ No newline at end of file
diff --git a/developer_manual/core/index.rst b/developer_manual/core/index.rst
index ea5f74b..e988f10 100644
--- a/developer_manual/core/index.rst
+++ b/developer_manual/core/index.rst
@@ -12,6 +12,7 @@ Core Development
unit-testing
theming
configfile
+ externalapi
ocs-share-api
Intro
@@ -29,3 +30,4 @@ Core related docs
* :doc:`theming`
* :doc:`configfile`
* :doc:`ocs-share-api`
+* :doc:`externalapi`
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-owncloud/owncloud-doc.git
More information about the Pkg-owncloud-commits
mailing list