<?xml version="1.0" encoding="UTF-8"?> <!-- vim: set ts=2 sw=2 tw=80 ai si: --> <chapter xml:id="chapter.client.programming" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" > <title>Application Programming</title> <para>THIS SECTION IS SUBJECT TO CHANGE. It has not been updated since we've added other services on top of the P4 Web API.</para> <simplesect xml:id="clientprog.content_types"> <title> Perforce Web API Content Types </title> <para> Almost all methods and return values send <literal>Content-Type</literal> as <literal>application/json</literal>. In the documentation, while we do accept <literal>application/x-www-form-urlencoded</literal> for most request bodies, we standardize on JSON for requests and responses. </para> <para> When you see a documented request 'form' field, you can interchange this with a form field or as a parameter of a JSON object sent in on input. </para> </simplesect> <simplesect xml:id="clientprog.authentication"> <title> Perforce Web API Authentication </title> <para> Perforce Web API methods require authentication as a Perforce user. Authentication uses the HTTP Basic Access Authentication scheme, except, the password of the user in the access header is either a Perforce ticket or a Perforce Web API session token. </para> <para> The Perforce ticket approach may be convenient when you need to reuse the ticket for more than one API. For example, you may want to use the Perforce Web API for administrative operations, and then handle some logic that submits files for a client with the C++ API. The Perforce ticket approach, however, is less secure than the Perforce Web API session token, because the Perforce ticket can be obtained in via each method request. </para> <para> For cases where you will only use the Perforce Web API, the session token method is likely more secure. Here, you will let the Perforce Web API generate a random session token that will be reused to subsequent calls. This session token is only valid with that instance of the Perforce Web API, and can not be reused with any other Perforce API. </para> </simplesect> <simplesect xml:id="clientprog.authentication.p4_ticket"> <title> Accessing the Perforce Web API using a Perforce ticket </title> <para> When you have a Perforce ticket for the user, you can use the ticket as the password for the Basic Authentication scheme to any command. </para> <para> For example, say the user <literal>jdoe</literal> has signed in and obtained the P4 ticket <literal>09899EBAD658FC3C41B425CA67E6F7CA</literal>. (This ticket can be obtained via the command <literal>p4 login -p</literal>.) The header for this ticket would look like <literal>Authorization: Basic amRvZTowOTg5OUVCQUQ2NThGQzNDNDFCNDI1Q0E2N0U2RjdDQQ==</literal>. </para> <para> This can be used in cases where your current application obtains and stores p4 tickets, which avoids having to create a P4 session below. </para> <para> Please note this will not work for host-locked tickets where the host is running on a different machine from the P4 Web API. The Perforce host connection should use the same IP address for the P4 Web API as the command that actually created the Perforce ticket. </para> </simplesect> <simplesect xml:id="clientprog.authentication.p4_session"> <title> Accessing the Perforce Web API using a session token </title> <para> You can also use the P4 Web API to generate session tokens that are only valid via the P4 Web API, which can be more secure. </para> <para> Sessions are created via the <link linkend="api.sessions.v1_sessions_POST"> <literal>POST /v1/sessions</literal></link> command. The result of this command is a GUID that can only be used by this P4 Web API server. Use this GUID as the password in the Basic Authentication scheme for any other command. </para> <para> For example, say you receive the session ID <literal>561547ba-6938-4b50-8a76-aca4849924c5</literal> for the user <literal>jdoe</literal>. Your authorization header would look like <literal>Authorization: Basic amRvZTo1NjE1NDdiYS02OTM4LTRiNTAtOGE3Ni1hY2E0ODQ5OTI0YzU=</literal>. </para> <para> This session ID is associated with a Perforce ticket. When that underlying ticket is invalidated, you will start to receive <literal>403 Forbidden</literal> errors from various commands. At that point you should regenerate a new session. </para> <para> Note that you can also delete the session ID using the <link linkend="api.sessions.v1_sessions_DELETE"> <literal>DELETE /v1/sessions</literal></link> command. For a web application, it may make sense to tye the underlying Perforce Web API session with your application's session management. </para> </simplesect> <simplesect xml:id="clientprog.client_api"> <title> Using the Ruby client API </title> <para> For Ruby client applications, a Ruby client API for the Perforce Web API has been created, to avoid you having to convert our JSON output to using objects that follow Ruby platform conventions. </para> <para> Getting started with the Perforce Web API can be a little easier with the client API. You will likely also want to use another project, <literal>p4util</literal>, which can download a Perforce server and set it up for testing. </para> <programlisting language="shell"> # Install Gem dependencies $ gem install p4_web_api --version='2014.2.0.pre1' $ gem install p4_web_api_client --version='2014.2.0.pre1' $ gem install p4util puma # Download and start up a Perforce server in the work/ directory $ p4util start # Start the P4 Web API instance using Puma, responding to requests at port 4567 $ p4_web_api -s Puma # Create a p4 account to become the superuser: # 1. Download the p4 command line client # 2. Create the 'jdoe' user (assume the user has created a `Password` of `example` # during the second step.) # 3. Update the protections table to make this user the superuser $ p4util download p4 $ work/p4 -p :1666 user -f jdoe $ work/p4 -p :1666 -u jdoe -P example protect </programlisting> <para> At this point, you can start to use the client API to say, create more users: </para> <programlisting language="ruby"> require 'p4_web_api_client' settings = { :user => 'jdoe', :password => 'example', :url => 'http://localhost:4567' } # Right now this creates a session when the connection is opened # This will automatically close the connection when done, deleting the session P4WebApiClient::Client.open(settings) do |client| client.create_user( :user => 'sueq', :full_name => 'Susie Q', :password => 'whereru' ) # There are Model classes for most system objects that can be used as well... client.create_user(P4WebApiClient::Models::User.new( :user => 'mmustermann', :full_name => 'Max Mustermann', :password => 'example', :email => 'mmustermann@example.com' )) end </programlisting> </simplesect> </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/03_clientprog.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. |