fishbowl-overview

fishbowl-overview.md

The fishbowl api itself is... weird.

Useful Links

• Fishbowl API
• Fishbowl Legacy API
• fishbowl-api python library

General

There are, many, oddities in the API, but for what we need to work on below is generally the ones you need to know about.

1. You might run into different encoding issues if someone add chinese characters in word and insert. Pulling data backout might break in interesting ways. Via the encoding type we once figured out what version of a Java library they were using (don't remember that now.
2. You can do SQL Quries as evidenced in the fishbowl-api library. Sometimes it is a better choice, but sometimes the api uses views to get data back.

Legacy VS Not(?)

The "Fishbowl Legacy API" is all XML based, and that is currently what we use. However, in the last year, or so, they have released a new API all based on JSON. However, it is not as awesome as it sounds.

The JSON api is literally the exact same as the XML api, except you build the document in JSON. The strucutre is still the same. An example.

{
	"FbiJson": {
		"Ticket": {
			"Key": "xTypHT/pZXZy6Re+H66kSA=="
		},
		"FbiMsgsRq": {
			"ExecuteQueryRq": {
				"Name": "PartList"
			}
		}
	}
}

The XML version of this is

<FbiXML>
	<Ticket>
		<Key>xTypHT/pZXZy6Re+H66kSA==</Key>
	</Ticket>
	<FbiMsgsRq>
		<ExecuteQueryRq>
			<Name>PartList</Name>
		</ExecuteQueryRq>
	</FbiMsgsRq>
</FbiXML>

So if you want to use the JSON version you just look at the "Legacy API", and reconstruct the requests in JSON.

Fishbowl API Fishbowl Legacy API

Connecting

When you think about an API generally you think about HTTP, but Fishbowl doesn't think about that. Nope they like raw socket connections. You will need to open up a stream, and send data accross.

Here is a link to how it is done in python.

https://github.com/patriotresearch/fishbowl-api/blob/master/fishbowl/api.py#L177-L215

One thing to note, you need to verify the connection is closed on error or completion. If you do not it will leave the user logged in for something like 30 minutes. The same user can only be logged in 5 times simultanesouly over the API. Using API's you can easily login too many times quickly.

Requests

First you are going to have to do some byte to xml/json conversion to and from the socket. That code is also in the fishbowl-api in python.

Here is a quick example of getting customers in XML.

Request

Simple Request

<FbiXml>
	<Ticket>
		<Key>OvJtHiwEwgv8d3RWClN1SA==</Key>
	</Ticket>
	<FbiMsgsRq>
		<CustomerListRq />
	</FbiMsgsRq>
</FbiXml>

Simple Response

(I am pulling the response from memory)

<FbiXml>
	<Ticket>
		<Key>OvJtHiwEwgv8d3RWClN1SA==</Key>
	</Ticket>
	<FbiMsgsRsp>
		<CustomerListRsp>
			<Customer>
				<Status>Normal</Status>
				<DefPaymentTerms>COD</DefPaymentTerms>
				<DefShipTerms>Prepaid</DefShipTerms>
				<TaxRate>None</TaxRate>
				<Name>Sam Ball</Name>
				<CreditLimit>1000000.00</CreditLimit>
				<TaxExempt>true</TaxExempt>
				<TaxExemptNumber>12345</TaxExemptNumber>
				<Note>Hello World</Note>
				<ActiveFlag>true</ActiveFlag>
				<DefaultSalesman>jen</DefaultSalesman>
				<DefaultCarrier>USPS</DefaultCarrier>
				<JobDepth>1</JobDepth>
				<Addresses>
					<Address>
						<Temp-Account>
							<Type>10</Type>
						</Temp-Account>
						<Name>Main Office</Name>
						<Attn>Attention</Attn>
						<Street>123 Neverland dr.</Street>
						<City>Murray</City>
						<Zip>84121</Zip>
						<Default>true</Default>
						<Residential>false</Residential>
						<Type>Main Office</Type>
						<State>
							<Name>Utah</Name>
							<Code>UT</Code>
							<CountryID>2</CountryID>
						</State>
						<Country>
							<Name>United States</Name>
							<Code>US</Code>
						</Country>
						<AddressInformationList>
							<AddressInformation>
								<Name>Main Office</Name>
								Address Data
								<Default>true</Default>
								<Type>Home</Type>
							</AddressInformation>
						</AddressInformationList>
					</Address>
				</Addresses>
				<CustomFields>
					<CustomField>
						<Type>CFT_TEXT</Type>
						<Name>Custom1</Name>
						<Info>Custom Data</Info>
					</CustomField>
				</CustomFields>
			</Customer>
		</CustomerListRsp>
	</FbiMsgsRsp>
</FbiXml>