<?xml version="1.0" encoding="UTF-8"?> <chapter xml:id="api.servers" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" > <title> Servers - List and manage server specifications </title> <para> These methods allow you to list, edit, and maintain server specifications in your Perforce server. </para> <informaltable> <tgroup cols="2"> <colspec colname="topic" colwidth="*"/> <colspec colname="description" colwidth="*"/> <thead> <row> <entry> <para>Path</para> </entry> <entry> <para>Description</para> </entry> </row> </thead> <tbody> <row> <entry> <para> <link linkend="api.servers.v1_servers_GET"> <literal>GET /v1/servers</literal> </link> </para> </entry> <entry> <para>List available servers</para> </entry> </row> <row> <entry> <para> <link linkend="api.servers.v1_servers_POST"> <literal>POST /v1/servers</literal> </link> </para> </entry> <entry> <para>Create a new server specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.servers.v1_servers_id_GET"> <literal>GET /v1/servers/[server]</literal> </link> </para> </entry> <entry> <para>Describe a single server specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.servers.v1_servers_id_PATCH"> <literal>PATCH /v1/servers/[server]</literal> </link> </para> </entry> <entry> <para>Update a server specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.servers.v1_servers_id_DELETE"> <literal>DELETE /v1/servers/[server]</literal> </link> </para> </entry> <entry> <para>Delete a server specification</para> </entry> </row> </tbody> </tgroup> </informaltable> <section xml:id="api.servers.v1_servers_GET"> <title><literal>GET /v1/servers</literal></title> <para> Lists available servers in the system. </para> <para> The resources of this list are summaries of servers in the system. For more details of each server, append the <literal>server</literal> property the end of this URL. </para> <para> There are no other parameters to this method. </para> <para> See the <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_server.html">Command Reference</ulink> for information about each field. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.servers.v1_servers_GET.response_data"> <title>Response Data</title> <para> Returns fields available from the <literal>p4 -ztag servers</literal> command. For more information, see the <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_servers.html"> <literal>p4 servers</literal> command reference. </ulink>. </para> <informaltable> <tgroup cols="4"> <colspec colname="parameter" colwidth="*"/> <colspec colname="description" colwidth="4*"/> <colspec colname="type" colwidth="*"/> <colspec colname="required" colwidth="*"/> <thead> <row> <entry> <para>Parameter</para> </entry> <entry> <para>Description</para> </entry> <entry> <para>Type</para> </entry> <entry> <para>Required</para> </entry> </row> </thead> <tbody> <row> <entry><literal>ServerID</literal></entry> <entry>The server name and primary ID</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Type</literal></entry> <entry>The server type (e.g., <local>standard</local>, <local>replica</local>)</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Services</literal></entry> <entry>The server services field</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Description</literal></entry> <entry>A text description about the server entry</entry> <entry>string</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.servers.v1_servers_GET.example"> <title>Example</title> <para>Our standard authenticated request format for listing servers:</para> <programlisting> GET /v1/servers HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj</programlisting> <para> Here's an example of a list with two servers in the response: </para> <programlisting language="json"> HTTP/1.1 200 OK Content-Type: application/json [{ "ServerID": "local", "Name": "", "Address": "", "Type": "server", "Services": "standard", "Description": "Created by super.\n" }, { "ServerID": "remote", "Name": "", "Address": "", "Type": "proxy", "Services": "proxy", "Description": "Created by super.\n" }]</programlisting> </simplesect> </section> <section xml:id="api.servers.v1_servers_POST"> <title><literal>POST /v1/servers</literal></title> <para> Creates a new server specification. </para> <para> Upon success, this will return a 303 redirect to the new server specification resource that has been created. </para> <para> If the server already exists, this method will replace the existing server completely. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.servers.v1_servers_POST.parameters"> <title>Parameters</title> <para> Here are some common fields to server definitions. </para> <para> Please refer to the <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_server.html"> <literal>p4 server</literal> command reference </ulink> for more details on fields. </para> <informaltable> <tgroup cols="5"> <colspec colname="parameter" colwidth="*"/> <colspec colname="description" colwidth="4*"/> <colspec colname="type" colwidth="*"/> <colspec colname="paramtype" colwidth="*" /> <colspec colname="required" colwidth="*"/> <thead> <row> <entry> <para>Parameter</para> </entry> <entry> <para>Description</para> </entry> <entry> <para>Type</para> </entry> <entry> <para>Parameter Type</para> </entry> <entry> <para>Required</para> </entry> </row> </thead> <tbody> <row> <entry><literal>ServerID</literal></entry> <entry>The server name and primary ID</entry> <entry>string</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry><literal>Type</literal></entry> <entry>The server type (e.g., <local>standard</local>, <local>replica</local>)</entry> <entry>string</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry><literal>Services</literal></entry> <entry>The server services field</entry> <entry>string</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry><literal>Description</literal></entry> <entry>A text description about the server entry</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.servers.v1_servers_id_POST.example"> <title>Example</title> <para> We'll create a simple server <literal>stuff</literal>. </para> <programlisting language="json"> POST /v1/servers HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj Content-Type: application/json { "ServerID": "new_server", "Type": "server", "Services": "standard" }</programlisting> <para> The return value should be a redirect to the details page of the new server. </para> <programlisting> HTTP/1.1 303 Found Location: http://example.com/p4/v1/servers/new_server</programlisting> <para> You may need to recall that the URL returned by a 303 response should be accessed via <literal>GET</literal>, and not via <literal>POST</literal>. </para> </simplesect> </section> <section xml:id="api.servers.v1_servers_id_GET"> <title><literal>GET /v1/servers/[server]</literal></title> <para> Return server details. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.servers.v1_servers_id_GET.parameters"> <title>Parameters</title> <informaltable> <tgroup cols="5"> <colspec colname="parameter" colwidth="*"/> <colspec colname="description" colwidth="4*"/> <colspec colname="type" colwidth="*"/> <colspec colname="paramtype" colwidth="*"/> <colspec colname="required" colwidth="*"/> <thead> <row> <entry> <para>Parameter</para> </entry> <entry> <para>Description</para> </entry> <entry> <para>Type</para> </entry> <entry> <para>Parameter Type</para> </entry> <entry> <para>Required</para> </entry> </row> </thead> <tbody> <row> <entry>server</entry> <entry>The server name.</entry> <entry>string</entry> <entry>path</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.servers.v1_servers_id_GET.response_data"> <title>Response Data</title> <para> Here are several common fields in use by server specifications. It is likely that you may see more in your output. </para> <para> Please refer to the <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_server.html"> <literal>p4 server</literal> command reference </ulink> for more details on fields. </para> <informaltable> <tgroup cols="4"> <colspec colname="parameter" colwidth="*"/> <colspec colname="description" colwidth="4*"/> <colspec colname="type" colwidth="*"/> <colspec colname="required" colwidth="*"/> <thead> <row> <entry> <para>Parameter</para> </entry> <entry> <para>Description</para> </entry> <entry> <para>Type</para> </entry> <entry> <para>Required</para> </entry> </row> </thead> <tbody> <row> <entry><literal>ServerID</literal></entry> <entry>The server name and primary ID</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Type</literal></entry> <entry>The server type (e.g., <local>standard</local>, <local>replica</local>)</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Services</literal></entry> <entry>The server services field</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Description</literal></entry> <entry>A text description about the server entry</entry> <entry>string</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.servers.v1_servers_id_GET.example"> <title>Example</title> <para> Here is an example request for the server <literal>local</literal>. </para> <programlisting> GET /v1/servers/local HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj</programlisting> <para> And the typical JSON response: </para> <programlisting language="json"> HTTP/1.1 200 OK Content-Type: application/json { "ServerID": "local", "Type": "server", "Services": "standard", "Description": "Created by super.\n" }</programlisting> </simplesect> </section> <section xml:id="api.servers.v1_servers_id_PATCH"> <title><literal>PATCH /v1/servers/[server]</literal></title> <para> Update server specifications. Only the specified parameters in the body will be changed. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.servers.v1_servers_id_PATCH.parameters"> <title>Parameters</title> <informaltable> <tgroup cols="5"> <colspec colname="parameter" colwidth="*"/> <colspec colname="description" colwidth="4*"/> <colspec colname="type" colwidth="*"/> <colspec colname="paramtype" colwidth="*" /> <colspec colname="required" colwidth="*"/> <thead> <row> <entry> <para>Parameter</para> </entry> <entry> <para>Description</para> </entry> <entry> <para>Type</para> </entry> <entry> <para>Parameter Type</para> </entry> <entry> <para>Required</para> </entry> </row> </thead> <tbody> <row> <entry><literal>server</literal></entry> <entry>The name of the server</entry> <entry>string</entry> <entry>path</entry> <entry>Yes</entry> </row> <row> <entry><literal>Type</literal></entry> <entry>The server type (e.g., <local>standard</local>, <local>replica</local>)</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Services</literal></entry> <entry>The server services field</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Description</literal></entry> <entry>A text description about the server entry</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.servers.v1_servers_id_PATCH.example"> <title>Example</title> <para> Here we'll update the description of the existing server <literal >new_server</literal>. </para> <programlisting language="json"> PATCH /v1/servers/new_server HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj Content-Type: application/json { "Description": "The updated new_server description.\n" }</programlisting> <para> The response will only contain the normal HTTP status information. </para> <programlisting> HTTP/1.1 200 OK</programlisting> </simplesect> </section> <section xml:id="api.servers.v1_servers_id_DELETE"> <title><literal>DELETE /v1/servers/[server]</literal></title> <para> Removes the server specification. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.servers.v1_servers_id_DELETE.parameters"> <title>Parameters</title> <informaltable> <tgroup cols="5"> <colspec colname="parameter" colwidth="*"/> <colspec colname="description" colwidth="4*"/> <colspec colname="type" colwidth="*"/> <colspec colname="paramtype" colwidth="*"/> <colspec colname="required" colwidth="*"/> <thead> <row> <entry> <para>Parameter</para> </entry> <entry> <para>Description</para> </entry> <entry> <para>Type</para> </entry> <entry> <para>Parameter Type</para> </entry> <entry> <para>Required</para> </entry> </row> </thead> <tbody> <row> <entry><literal>server</literal></entry> <entry>The server name.</entry> <entry>string</entry> <entry>path</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.servers.v1_servers_id_DELETE.example"> <title>Example</title> <para> Delete the server <literal>new_server</literal> </para> <programlisting language="json"> DELETE /v1/servers/new_server HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj</programlisting> <para> The response will only contain the normal HTTP status information. </para> <programlisting> HTTP/1.1 200 OK</programlisting> </simplesect> </section> </chapter>
# | Change | User | Description | Committed | |
---|---|---|---|---|---|
#2 | 13972 | tjuricek |
Removing old microservice implementations. The system is now mostly a monolith. Eventually there will be a websocket service. |
||
#1 | 13458 | tjuricek |
Revising P4 Web API docbook documentation to become the Perforce Web Services guide. Right now this is just focused on the Qt SDK. The remaining protocol documentation, etc, will happen eventually. |
||
//guest/perforce_software/helix-web-services/main/p4_web_api/p4_web_api/docbook/xml/methods/servers.xml | |||||
#1 | 13412 | tjuricek |
Initial version of the web-services mainline. This is a collection of several projects, that will likely often get released together, though many of them may not always be relevant. See the README for more information. |