<?xml version="1.0" encoding="UTF-8"?> <chapter xml:id="api.streams" 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> Streams - List and manage stream specifications </title> <para> These methods allow you to list, edit, and maintain stream 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.streams.v1_streams_GET"> <literal>GET /v1/streams</literal> </link> </para> </entry> <entry> <para>List available streams</para> </entry> </row> <row> <entry> <para> <link linkend="api.streams.v1_streams_POST"> <literal>POST /v1/streams</literal> </link> </para> </entry> <entry> <para>Create a new stream specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.streams.v1_streams_id_GET"> <literal>GET /v1/streams/[stream path]</literal> </link> </para> </entry> <entry> <para>Describe a single stream specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.streams.v1_streams_id_PATCH"> <literal>PATCH /v1/streams/[stream path]</literal> </link> </para> </entry> <entry> <para>Update a stream specification</para> </entry> </row> <row> <entry> <para> <link linkend="api.streams.v1_streams_id_DELETE"> <literal>DELETE /v1/streams/[stream path]</literal> </link> </para> </entry> <entry> <para>Delete a stream specification</para> </entry> </row> </tbody> </tgroup> </informaltable> <section xml:id="api.streams.v1_streams_GET"> <title><literal>GET /v1/streams</literal></title> <para> Lists available streams in the system. </para> <para> The resources of this list are summaries of streams in the system. For more details of each stream, append the stream path to the end of this URL. </para> <para> There are no other parameters to this method. </para> <para> This method requires authentication. See <link linkend="streamprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.streams.v1_streams_GET.response_data"> <title>Response Data</title> <para> Returns fields available from the <literal>p4 -ztag streams</literal> command. For more information, see the <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_streams.html"> <literal>p4 streams</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>Stream</literal></entry> <entry>The stream name. Append the part after the first two slashes to obtain the path to append to this URL for the singular GET request.</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Owner</literal></entry> <entry>The Perforce login of the user that owns this stream</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Name</literal></entry> <entry>The stream name, used in different IDs</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Parent</literal></entry> <entry>The stream parent name or <literal>none</literal></entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Type</literal></entry> <entry>The stream type which indicates standard configuration rules</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Options</literal></entry> <entry>Shorthand for options of the stream configuration</entry> <entry>string</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.streams.v1_streams_GET.example"> <title>Example</title> <para>Our standard authenticated request format for listing streams:</para> <programlisting> GET /v1/streams HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj</programlisting> <para> Here's an example of a list with one stream in the response: </para> <programlisting language="json"> HTTP/1.1 200 OK Content-Type: application/json [ { "Stream": "//streams/my_project", "Update": 1413333994, "Access": 1413333994, "Owner": "super", "Name": "my_project", "Parent": "none", "Type": "mainline", "Options": "allsubmit unlocked notoparent nofromparent" } ]</programlisting> </simplesect> </section> <section xml:id="api.streams.v1_streams_POST"> <title><literal>POST /v1/streams</literal></title> <para> Creates a new stream specification. </para> <para> Upon success, this will return a 303 redirect to the new stream specification resource that has been created. </para> <para> If the stream already exists, this method will replace the existing stream completely. </para> <para> This method requires authentication. See <link linkend="streamprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.streams.v1_streams_POST.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>Stream</literal></entry> <entry>The stream name. Append the part after the first two slashes to obtain the path to append to this URL for the singular GET request.</entry> <entry>string</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry><literal>Owner</literal></entry> <entry>The Perforce login of the user that owns this stream</entry> <entry>string</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry><literal>Name</literal></entry> <entry>The stream name, used in different IDs</entry> <entry>string</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry><literal>Parent</literal></entry> <entry>The stream parent name or <literal>none</literal></entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Type</literal></entry> <entry>The stream type which indicates standard configuration rules</entry> <entry>string</entry> <entry>body</entry> <entry>Yes</entry> </row> <row> <entry><literal>Options</literal></entry> <entry>Shorthand for options of the stream configuration</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Paths</literal></entry> <entry>An array of path mappings for the stream</entry> <entry>array</entry> <entry>body</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.streams.v1_streams_id_POST.example"> <title>Example</title> <para> We'll create a simple stream <literal>my_project_dev</literal> that should be a development stream based on the parent <literal>my_project</literal>. </para> <programlisting language="json"> POST /v1/streams HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj Content-Type: application/json { "Stream": "//streams/my_project_dev", "Owner": "jdoe", "Name": "my_project_dev", "Type": "development", "Parent": "//streams/my_project", "Paths": ["share ..."] }</programlisting> <para> The return value should be a redirect to the details page of the new stream. </para> <programlisting> HTTP/1.1 303 Found Location: http://example.com/p4/v1/streams/streams/my_project_dev</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.streams.v1_streams_id_GET"> <title><literal>GET /v1/streams/[stream path]</literal></title> <para> Return stream details. </para> <para> This method requires authentication. See <link linkend="streamprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.streams.v1_streams_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>streamp path</entry> <entry>The path part of the Stream ID, basically strip out the leading <literal>//</literal> and use this.</entry> <entry>string</entry> <entry>path</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.streams.v1_streams_id_GET.response_data"> <title>Response Data</title> <para> Returns fields available from the <literal>p4 -ztag stream</literal> command. For more information, see the <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_stream.html"> <literal>p4 stream</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>Stream</literal></entry> <entry>The ID of the stream</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Owner</literal></entry> <entry>The Perforce login of the user that owns the stream</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Name</literal></entry> <entry>A label of this stream</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Parent</literal></entry> <entry>The id of the parent stream or <literal>none</literal></entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Type</literal></entry> <entry>The type of stream, for example <literal>mainline</literal>, <literal>development</literal>, <literal>task</literal>, <literal>release</literal></entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Options</literal></entry> <entry>The options of the stream specification</entry> <entry>string</entry> <entry>Yes</entry> </row> <row> <entry><literal>Paths</literal></entry> <entry>One or more lines that define file paths in the stream view.</entry> <entry>string</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.streams.v1_streams_id_GET.example"> <title>Example</title> <para> Here is an example request for the stream <literal>//streams/my_project_dev</literal>. This is a fairly simple stream, containing only one view mapping. </para> <programlisting> GET /v1/streams/streams/my_project_dev 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 { "Stream": "//streams/my_project_dev", "Update": 1413333994, "Access": 1413333994, "Owner": "jdoe", "Name": "my_project_dev", "Parent": "//streams/my_project", "Type": "development", "Options": "allsubmit unlocked notoparent nofromparent", "Paths": ["share ..."], "firmerThanParent": "false", "baseParent": "//streams/my_project" }</programlisting> </simplesect> </section> <section xml:id="api.streams.v1_streams_id_PATCH"> <title><literal>PATCH /v1/streams/[stream]</literal></title> <para> Update stream specifications. Only the specified parameters in the body will be changed. </para> <para> This method requires authentication. See <link linkend="streamprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.streams.v1_streams_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>stream path</literal></entry> <entry>The ID of the stream, minus the leading <literal>//</literal></entry> <entry>string</entry> <entry>path</entry> <entry>Yes</entry> </row> <row> <entry><literal>Owner</literal></entry> <entry>The Perforce login of the user that owns the stream</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Name</literal></entry> <entry>A label of this stream</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Parent</literal></entry> <entry>The id of the parent stream or <literal>none</literal></entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Type</literal></entry> <entry>The type of stream, for example <literal>mainline</literal>, <literal>development</literal>, <literal>task</literal>, <literal>release</literal></entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Options</literal></entry> <entry>The options of the stream specification</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> <row> <entry><literal>Paths</literal></entry> <entry>One or more lines that define file paths in the stream view.</entry> <entry>string</entry> <entry>body</entry> <entry>No</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.streams.v1_streams_id_PATCH.example"> <title>Example</title> <para> Here we'll update the name of the existing stream <literal >//streams/my_stream_dev</literal>. </para> <programlisting language="json"> PATCH /v1/streams/streams/my_stream_dev HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj Content-Type: application/json { "Name": "my_stream_development" }</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.streams.v1_streams_id_DELETE"> <title><literal>DELETE /v1/streams/[stream]</literal></title> <para> Removes the stream specification. </para> <para> This method requires authentication. See <link linkend="streamprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.streams.v1_streams_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>stream</literal></entry> <entry>The stream name.</entry> <entry>string</entry> <entry>path</entry> <entry>Yes</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.streams.v1_streams_id_DELETE.example"> <title>Example</title> <para> Delete the stream <literal>//streams/my_stream_dev</literal> </para> <programlisting language="json"> DELETE /v1/streams/streams/my_stream_dev 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/streams.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. |