6n1 API mEF

6n1 API mEF

##Introduction
This document will specify the API that will be used to send Tax Returns from the FileMaker based 6n1 to the .NET application that is being built by Benchmark to do the actually eFileing with the Federal mEF system.

FileMaker has a reasonable HTTP client, although it is best to keep things as simple as possible.  Complex request types like multi-part forms are more difficult. Its best if we can keep to using only text or json formatted data. Raw binaries are tougher.

The intent is to use a REST like architecture. We may not need to support all of the VERBS for each resource.  There isn’t really a need to DELETE a firm for example.
Authentication
We’ll keep this simple and use Basic Auth.  There will only be two usernames and password pairs needed. One for “end user” access and one for “admin access”.  However, at this point there are no features that require “admin” access.  We should just keep that possibility open.

All of 6n1 users will use the same username and password.  They will never see the username and password. It will be hidden in the code.

Firm Identification
Each firm that uses 6n1 has a unique ID.  That ID will be passed as a path segment.  For example performing a GET against the url shown below should return all the returns for a the firm with the unique ID of 1234567.

/firms/1234567/returns

Encoding
Data will be sent and received as JSON.  

Binary files will be Base64 encoded before being placed into the JSON string. This should work, although, this will need to be confirmed.  Base64 does increase the size of of attachments by 33%. 

Draft Status
All of the JSON structures below should be considered as examples.  The actual structure may very.  Also the JSON has not been validated in anyway.

Errors
We can handle all the typical HTTP Errors. But when possible it would be helpful if the error and info was also passed back in the JSON response.  For example:
	
{
	“success”: false
	“errorCode” : 401
	“errorMessage”: “unauthorized”
}

The goal is that there is always just one place to check for errors, and gather more information about them.  The exception of course is any HTTP 500 errors, which probably can’t be handled this way.  Thats OK.

REST Resources

Returns

Get Returns for a Firm
	Method: Get
	Path: /firms/<firm_id>/returns

Optional URL Parameters
taxYear - if taxYear=2014 is passed as a URL parameter, then it should only return the returns that have been filed for this year.

Response: JSON
		{
			“success”: true,
	“count”: <number of returns found>,
	“data”: [
	{“returnID”: <ReturnID>, “type”: <returnType>, “status”: <return status> }
]
}

Create a return
method: POST 
   	path: /firms/<firm_id>/returns
	postBody: JSON. This structure should be considered very preliminary

```JSON{
	“returnData” : <data for the return>
	“attachments” : [
		“name”: <nameOfAttachment>
“data” : <base64EncodedData>
]

}```
   
   	Response:  JSON
   		{
			success: true,
	count: 1,
	data: [
	{“returnID”: <ReturnID>, “type”: <returnType>, “status”: <return status> }
]
}		

Retrieve a Return
	method: GET
	path: /returns/<returnid>