Large submits:

The API ensures that submits are atomic, meaning that if something goes wrong during the submit that the state of the system is not impacted.  This is a great and useful feature but can lead to problems when submits become too big.  There is no hard rule on what is too big, but there are some factors that greatly increase the amount of time and resources used during submit.  Mixing name inserts/updates with case inserts/updates can cause the submit as a whole to take significantly longer, and while the submit is in progress the data being modified cannot be changed by anyone else.  This can lead in some cases to database deadlocks or timeouts.  Simply breaking the submit into smaller parts will help in most situations.  Keep in mind that submitting a case with a lot of case-related entities is generally acceptable, but if there are more than a few name insert/updates mixed then you may begin to see some problems arise.

Queries:

The API query language is very flexible and allows for a wide variety of usages.  In many situations it is very helpful to include related data in the query result, e.g. retrieving a name with all of the addresses, phones and email records.  Those queries generally perform well as long as the included collections are only one hop away from the root of the Find or Get operation.  It is possible to include data that is more than one hop away, but doing so may result in queries that are unacceptably slow.  For example, a query to Find active cases and include the case involved names along with the case involved name’s tasks may result in a query that causes timeouts.  In summary, use included collections when needed, but avoid requesting data beyond a single hop from the root.

Retries:

Occasionally there will be situations when a call to the API fails on the first try, but will succeed if retried immediately.  One such example is a submit that ends up in a deadlock situation and the database chooses your submit as the deadlock victim.  There was likely nothing wrong with the data being submitted but due to the state of the system at that moment in time your submit was unsuccessful.  Simply detecting that situation and resubmitting will often succeed.  There are other situations where retries will never help, such as attempting to submit an entity without providing a required value.  Those errors usually only happen during development and are easily corrected.

Credentials:

When the API is configured for basic authentication, your client code must provide a valid username and password.  Those values must be properly protected to ensure that a malicious party cannot easily gain access to them.  A common way to do this in .Net code is to write the values in the settings portion of the app.config file and then use the windows Data Protection API (DPAPI) to encrypt the settings.

Logging:

It is a good idea, especially during development and testing, to keep a log of API activity.  This logging should include all errors thrown by the API, and could include logging of initially data or actions performed.  This allows you to be able to go back and validate you performed the work you thought you performed. It allows you to be able to determine when errors or functionality were introduced into your code.  Should you start to experience issues with your development, this logging will be an invaluable debugging tool for you.  This logging information will also be very valuable should you need to post to the API Support forum.

Load Testing:

It is important to test your API code under real load.  The API will increase the load on the web server and database, and so you will want to make sure you understand the performance impact your API project will have.  This is especially important because the impact of your code on the web server and database will directly affect the experience of JustWare client users.