HTTPS API Specifications

Transcription

1 HTTPS API Specifications June 17, 2016 P a g e 1 - HTTPS API Specifications

2 Contents HTTPS API Overview... 3 Terminology... 3 Process Overview... 3 Parameters... 4 Responses... 5 Examples... 6 PERL on a UNIX system (Using LWP)... 6 PHP on a UNIX system (Using curl)... 7 Visual Basic.Net (HTTPWebRequest)... 8 P a g e 2 - HTTPS API Specifications

3 HTTPS API Overview This API is for data set submission over HTTPS. This method does not allow for PGP encrypted files. If you wish to submit PGP encrypted files, you must use the FTP, SFTP or Manual Upload Form transmission method. The data set is secure via an SSL certificate. The connection encryption is an AES-256 SSL certificate. Submitting a data set over HTTPS is the preferred method for any group wishing to submit data sets on multiple organizations. Terminology Term Data Set EM File DP File EL File TERM File API Loader Script AuthString Definition A set of files that need/can be submitted through this data feed system The required employee file in the data set The required dependent file in the data set The required election file in the data set The optional event file in the data set The HTTPS destination script used for accepting a data set The authentication string used in lieu of a username and password for HTTPS authentication Process Overview Once you are ready to submit files over HTTPS, you need a couple pieces of information from Data Feed Support (feeds@cobraguard.net). The first value you need is an AuthString, this is the means of authenticating an account. The second value you need is an Org ID. The Org ID is assigned during the initial account setup. All data must be passed through POST. Any other method is not allowed. Once a data set is submitted, it is queued for processing just like the FTP transmission method. P a g e 3 - HTTPS API Specifications

4 Parameters In each data set post there are five required keys and one optional key. The required keys are: Key Required Description EMFile Y This contains the employee CSV DPFile Y This contains the dependent CSV ELFile Y This contains the election CSV TERMFile N This contains the event CSV AuthString Y Value assigned to you by data feed support OrgID Y Organization ID assigned during the initial account setup P a g e 4 - HTTPS API Specifications

5 Responses Once you have submitted your data set you will get an immediate response from the API about the submission of the data set. The responses you could receive are: Return Code FILES_NOT_FOUND ORG_NOT_FOUND INVALID_AUTH_STRING_OR_ORGID ACCOUNT_ACCESS_DENIED TEST_SUCCESSFULL SUCCESSFULL Definition 1 or more files were missing from your data set An invalid Org ID was submitted The submitted AuthString did not match the Org ID Account is not setup for file feed transmissions Success, in test mode Success, in production mode P a g e 5 - HTTPS API Specifications

6 Examples PERL on a UNIX system (Using LWP) #!/usr/bin/perl use strict; use LWP::UserAgent my $Response = $UserAgent->request(POST '', [ 'EMFile' => ["1234_ _EM_Refresh.csv"], 'ELFile' => ["1234_ _EL_Refresh"], 'DPFile' => ["1234_ _DP_Refresh"], 'AuthString' => 'f51fe56e381a1782aa26e7ef4a2d65ff', 'OrgID' => '1234' ], 'Content_Type' => 'form-data' ); P a g e 6 - HTTPS API Specifications

7 PHP on a UNIX system (Using curl) #!/usr/bin/php $postdata = array(); $postdata['emfile'] = "@1234_ _EM_Refresh.csv"; $postdata['elfile'] = "@1234_ _EL_Refresh.csv"; $postdata['dpfile'] = "@1234_ _DP_Refresh.csv"; $postdata['authstring'] = "f51fe56e381a1782aa26e7ef4a2d65ff"; $postdata['orgid'] = "1234"; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, ' ); curl_setopt($ch, CURLOPT_RETURNTRANSFER,1); curl_setopt($ch, CURLOPT_POST, 1 ); curl_setopt($ch, CURLOPT_POSTFIELDS, $postdata ); $response = curl_exec( $ch ); P a g e 7 - HTTPS API Specifications

8 Visual Basic.Net (HTTPWebRequest) Public Structure feedfile Public Const EMFile As String = "EMFile" Public Const ELFile As String = "ELFile" Public Const DPFile As String = "DPFile" Public Const TERMFile As String = "TERMFile" Public pathtofile As String Public feedtype As String Public Sub New(ByVal pathtofile As String, ByVal feedtype As String) Me.pathToFile = pathtofile Me.feedType = feedtype End Sub End Structure Public Sub uploadfeed() Dim uploaduri As String = " Dim authstring As String = "f51fe56e381a1782aa26e7ef4a2d65ff" Dim orgid As Integer = 1234 Dim filestoupload() As feedfile = New feedfile(3) _ {New feedfile("1234_ _em_refresh.csv", feedfile.emfile), _ New feedfile("1234_ _dp_refresh.csv", feedfile.dpfile), _ New feedfile("1234_ _el_refresh.csv", feedfile.elfile), _ New feedfile("1234_ _term_refresh.csv", feedfile.termfile)} Dim boundary As String = IO.Path.GetRandomFileName() ' setup the request Dim request As HttpWebRequest = HttpWebRequest.Create(uploadURI) request.method = "POST" request.contenttype = "multipart/form-data; boundary=" & boundary ' add each file to upload to the request Dim memstream As Stream = New System.IO.MemoryStream() ' build the POST variables Dim postdata As New System.Text.StringBuilder() postdata.appendline("--" & boundary) postdata.appendline("content-disposition: form-data; name=" & Chr(34) & "AuthString" & Chr(34)) postdata.appendline() postdata.appendline(authstring) postdata.appendline("--" & boundary) P a g e 8 - HTTPS API Specifications

9 postdata.appendline("content-disposition: form-data; name=" & Chr(34) & "OrgID" & Chr(34)) postdata.appendline() postdata.appendline(orgid) Dim postbytes() As Byte = System.Text.Encoding.UTF8.GetBytes(postData.ToString) memstream.write(postbytes, 0, postbytes.length) Dim x As Integer For x = 0 To filestoupload.length - 1 Try Dim filestream As FileStream = New FileStream(filesToUpload(x).pathToFile, FileMode.Open) ' build the multi-part request header Dim header As New System.Text.StringBuilder() header.appendline("--" & boundary) header.append("content-disposition: form-data; name=" & Chr(34) & filestoupload(x).feedtype & Chr(34) & ";") header.appendformat("filename={0}{1}{2}", Chr(34), IO.Path.GetFileName(filesToUpload(x).pathToFile), Chr(34)) header.appendline() header.appendline("content-type: application/octet-stream") header.appendline() Dim headerbytes() As Byte = System.Text.Encoding.UTF8.GetBytes(header.ToString) Dim boundarybytes() As Byte = System.Text.Encoding.ASCII.GetBytes(vbNewLine & "--" & boundary & "--" & vbnewline) Dim readbuffer(filestream.length) As Byte ' read the data from the input stream filestream.read(readbuffer, 0, filestream.length) memstream.write(headerbytes, 0, headerbytes.length) memstream.write(readbuffer, 0, filestream.length) memstream.write(boundarybytes, 0, boundarybytes.length) filestream.close() Catch ex As FileNotFoundException Next ' file does not exist? End Try Dim tmpbuffer(memstream.length) As Byte memstream.position = 0 memstream.read(tmpbuffer, 0, memstream.length) memstream.close() ' finish setting up the request P a g e 9 - HTTPS API Specifications

10 request.contentlength = tmpbuffer.length ' write the data to the request stream Dim requeststream As Stream = request.getrequeststream() requeststream.write(tmpbuffer, 0, tmpbuffer.length) Try ' send the request Dim response As HttpWebResponse = request.getresponse() If response.statuscode = HttpStatusCode.OK Then ' read the http response data & check return status Dim responsestream As StreamReader = New StreamReader(response.GetResponseStream) Dim responsedata As String = responsestream.readtoend() Console.WriteLine(responseData) End If ' clean up responsestream.close() Catch ex As Exception ' something went wrong; handle the exception accordingly End Try requeststream.close() End Sub P a g e 10 - HTTPS API Specifications