API writer

An API writer is a technical writer who writes documents that describe an application programming interface (API). The primary audience includes programmers, developers, system architects, and system designers.

Overview

An API is a basic library consisting of interfaces, functions, classes, structures, enumerations, etc. for building a software application. It is used by development teams to interact with and extend the software. An API for a given programming language and system may consist of system-defined and user-defined constructs. As the number and complexity of these constructs increases, it becomes very tedious for developers to remember all of the functions and the parameters defined. Hence, the API writers play a key role in building software applications.

Due to the technical subject matter, API writers must understand application source code enough to extract the information that API documents require. Some common tools used by API writers include computer software that extracts documentation placed by programmers in the source code in a structured manner, preserving the relationships between those comments and the programming constructs they document.

API writers must also understand the software platform/product and document the new features or changes as part of the new software release. The schedule of software releases varies from organization to organization. The writers need to understand the software life cycle well and integrate themselves into the Systems Development Life Cycle.

API writers in the United States generally follow The Chicago Manual of Style for grammar and punctuation.

Qualifications

API writers typically possess a mix of programming and language skills; many API writers have backgrounds in programming or technical writing.

• Computer programming background (Knowledge of C, C++, Java, PHP, Assembly, or other programming languages)
• Knowledge of formatting standards like Doxygen, Javadoc, or DITA
• Knowledge of editors and tools, like FrameMaker
• Excellent communication and writing skills to interact with developers

Expert API/SDK writers can easily become programming writers.

API writing process

About 60% of the time spent in the writing process consists of analyzing and understanding the source code and planning the document(s). The remaining 40% of the time would typically be spent writing and reviewing the document(s). It is often the case that the analytical, planning, and writing stages do not occur in a strictly linear fashion.

A good foundation of a variety of programming skills is well-complemented by an ability to communicate effectively, especially when the writer seeks to develop a fluent level of understanding with developers.

This process is one of the most important challenges faced by technical writers. The writing and evaluation criteria vary between organizations. Some of the most effective API documents are written by those who are adequately capable of understanding the workings of a particular application, so that they can relate the software to the users or the various component constructs to the overall purpose of the program. API writers may also be at least partly responsible for authoring end-user product documentation.

Product

API writers produce documents that include:

• API Reference Guides
• Programmers' Guides
• Developer Manuals
• Administration Manuals
• Installation Guides

Books

• Documenting APIs: Writing Developer Documentation for Java APIs and SDKs

2017-1-28-Webmaster 顓如

【中文】 ource的副本 基於上面的迴聲後端的POST調用的演示。 請求正文需要包含JSON格式的數據（參見下面的示例）。 策略用於將JSON中發送的任何請求自動轉換為XML。 在現實世界的情況下，這可以用於使現代客戶端與傳統後端通信。

【英文】 Copy of /resource A demonstration of a POST call based on the echo backend above. The request body is expected to contain JSON-formatted data (see example below). A policy is used to automatically transform any request sent in JSON directly to XML. In a real-world scenario this could be used to enable modern clients to speak to a legacy backend. 要求 URL https://zhuanru.azure-api.net/echo/copy-of-/resource[?subscription-key] 參數 subscription-key (optional) string subscription key in url 要求標頭 Ocp-Apim-Subscription-Key(optional) string subscription key in header Ocp-Apim-Subscription-Key string 已將 API 金鑰指派給個人，以便其存取 API。您可以在您的帳戶中找到 API 金鑰。

要求內文 回應 200

程式碼範例 Curl

@ECHO OFF

curl -v -X POST "https://zhuanru.azure-api.net/echo/copy-of-/resource?subscription-key={string}" -H "Ocp-Apim-Subscription-Key: " -H "Ocp-Apim-Subscription-Key: {subscription key}"

--data-ascii "{body}"

C#

using System; using System.Net.Http.Headers; using System.Text; using System.Net.Http; using System.Web;

namespace CSHttpClientSample {

   static class Program
   {
       static void Main()
       {
           MakeRequest();
           Console.WriteLine("Hit ENTER to exit...");
           Console.ReadLine();
       }
       
       static async void MakeRequest()
       {
           var client = new HttpClient();
           var queryString = HttpUtility.ParseQueryString(string.Empty);

           // Request headers
           client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "");
           client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

           // Request parameters
           queryString["subscription-key"] = "{string}";
           var uri = "https://zhuanru.azure-api.net/echo/copy-of-/resource?" + queryString;

           HttpResponseMessage response;

           // Request body
           byte[] byteData = Encoding.UTF8.GetBytes("{body}");

           using (var content = new ByteArrayContent(byteData))
           {
              content.Headers.ContentType = new MediaTypeHeaderValue("< your content type, i.e. application/json >");
              response = await client.PostAsync(uri, content);
           }

       }
   }

}

Java

// // This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/) import java.net.URI; import org.apache.http.HttpEntity; import org.apache.http.HttpResponse; import org.apache.http.client.HttpClient; import org.apache.http.client.methods.HttpGet; import org.apache.http.client.utils.URIBuilder; import org.apache.http.impl.client.HttpClients; import org.apache.http.util.EntityUtils;

public class JavaSample {

   public static void main(String[] args) 
   {
       HttpClient httpclient = HttpClients.createDefault();

       try
       {
           URIBuilder builder = new URIBuilder("https://zhuanru.azure-api.net/echo/copy-of-/resource");

           builder.setParameter("subscription-key", "{string}");

           URI uri = builder.build();
           HttpPost request = new HttpPost(uri);
           request.setHeader("Ocp-Apim-Subscription-Key", "");
           request.setHeader("Ocp-Apim-Subscription-Key", "{subscription key}");

           // Request body
           StringEntity reqEntity = new StringEntity("{body}");
           request.setEntity(reqEntity);

           HttpResponse response = httpclient.execute(request);
           HttpEntity entity = response.getEntity();

           if (entity != null) 
           {
               System.out.println(EntityUtils.toString(entity));
           }
       }
       catch (Exception e)
       {
           System.out.println(e.getMessage());
       }
   }

}

JavaScript

<!DOCTYPE html> <html> <head>

   <title>JSSample</title>
   <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>

</head> <body>

<script type="text/javascript">

   $(function() {
       var params = {
           // Request parameters
           "subscription-key": "{string}",
       };
     
       $.ajax({
           url: "https://zhuanru.azure-api.net/echo/copy-of-/resource?" + $.param(params),
           beforeSend: function(xhrObj){
               // Request headers
               xhrObj.setRequestHeader("Ocp-Apim-Subscription-Key","");
               xhrObj.setRequestHeader("Ocp-Apim-Subscription-Key","{subscription key}");
           },
           type: "POST",
           // Request body
           data: "{body}",
       })
       .done(function(data) {
           alert("success");
       })
       .fail(function() {
           alert("error");
       });
   });

</script> </body> </html>

Objc

1. import <Foundation/Foundation.h>

int main(int argc, const char * argv[]) {

   NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
   
   NSString* path = @"https://zhuanru.azure-api.net/echo/copy-of-/resource";
   NSArray* array = @[
                        // Request parameters
                        @"entities=true",
                        @"subscription-key={string}",
                     ];
   
   NSString* string = [array componentsJoinedByString:@"&"];
   path = [path stringByAppendingFormat:@"?%@", string];

   NSLog(@"%@", path);

   NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
   [_request setHTTPMethod:@"POST"];
   // Request headers
   [_request setValue:@"" forHTTPHeaderField:@"Ocp-Apim-Subscription-Key"];
   [_request setValue:@"{subscription key}" forHTTPHeaderField:@"Ocp-Apim-Subscription-Key"];
   // Request body
   [_request setHTTPBody:[@"{body}" dataUsingEncoding:NSUTF8StringEncoding]];
   
   NSURLResponse *response = nil;
   NSError *error = nil;
   NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];

   if (nil != error)
   {
       NSLog(@"Error: %@", error);
   }
   else
   {
       NSError* error = nil;
       NSMutableDictionary* json = nil;
       NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
       NSLog(@"%@", dataString);
       
       if (nil != _connectionData)
       {
           json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
       }
       
       if (error || !json)
       {
           NSLog(@"Could not parse loaded json with error:%@", error);
       }
       
       NSLog(@"%@", json);
       _connectionData = nil;
   }
   
   [pool drain];

   return 0;

}

PHP

<?php // This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/) require_once 'HTTP/Request2.php';

$request = new Http_Request2('https://zhuanru.azure-api.net/echo/copy-of-/resource'); $url = $request->getUrl();

$headers = array(

   // Request headers
   'Ocp-Apim-Subscription-Key' => ,
   'Ocp-Apim-Subscription-Key' => '{subscription key}',

);

$request->setHeader($headers);

$parameters = array(

   // Request parameters
   'subscription-key' => '{string}',

);

$url->setQueryVariables($parameters);

$request->setMethod(HTTP_Request2::METHOD_POST);

// Request body $request->setBody("{body}");

try {

   $response = $request->send();
   echo $response->getBody();

} catch (HttpException $ex) {

   echo $ex;

}

?>

Python

1. 1. 1. 1. 1. 1. 1. 1. 1. 1. 1. Python 2.7 #############

import httplib, urllib, base64

headers = {

   # Request headers
   'Ocp-Apim-Subscription-Key': ,
   'Ocp-Apim-Subscription-Key': '{subscription key}',

}

params = urllib.urlencode({

   # Request parameters
   'subscription-key': '{string}',

})

try:

   conn = httplib.HTTPSConnection('zhuanru.azure-api.net')
   conn.request("POST", "/echo/copy-of-/resource?%s" % params, "{body}", headers)
   response = conn.getresponse()
   data = response.read()
   print(data)
   conn.close()

except Exception as e:

   print("[Errno {0}] {1}".format(e.errno, e.strerror))

1. 1. 1. 1. 1. 1. 1. 1. 1. 1. 1. Python 3.2 #############

import http.client, urllib.request, urllib.parse, urllib.error, base64

headers = {

   # Request headers
   'Ocp-Apim-Subscription-Key': ,
   'Ocp-Apim-Subscription-Key': '{subscription key}',

}

params = urllib.parse.urlencode({

   # Request parameters
   'subscription-key': '{string}',

})

try:

   conn = http.client.HTTPSConnection('zhuanru.azure-api.net')
   conn.request("POST", "/echo/copy-of-/resource?%s" % params, "{body}", headers)
   response = conn.getresponse()
   data = response.read()
   print(data)
   conn.close()

except Exception as e:

   print("[Errno {0}] {1}".format(e.errno, e.strerror))

Ruby

require 'net/http'

uri = URI('https://zhuanru.azure-api.net/echo/copy-of-/resource')

query = URI.encode_www_form({

   # Request parameters
   'subscription-key' => '{string}'

})

if uri.query && uri.query.length > 0

   uri.query += '&' + query

else

   uri.query = query

end

request = Net::HTTP::Post.new(uri.request_uri)

1. Request headers

request['Ocp-Apim-Subscription-Key'] =

1. Request headers

request['Ocp-Apim-Subscription-Key'] = '{subscription key}'

1. Request body

request.body = "{body}"

response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|

   http.request(request)

end

puts response.body

See also

• Application programming interface (API)
• Software documentation
• Technical writer
• Technical communication
• Technical communication tools
• Comparison of documentation generators

External links

Technical writing

• Free Wikiversity Technical Writing Courses
• EServer Technical Communication (and Technical Writing) Library
• The Death of the Technical Author?