General API structure

All Dashboard Service API signatures use the following pattern.

ServiceResponse DoSomething (CallingContext callingContext, DoSomethingInput input, out DoSomethingResult result);

ServiceResponse—The DoSomething call returns a data structure of type ServiceResponse. It does not detail how the DoSomething operation proceeded, but rather it details any errors in making the web service call. For example, it would return a problem with the URL or connection. If the ServiceResponse structure shows that the call succeeded, then the web service call was successful. You will still need to check the result of DoSomething.

The ServiceResponse data structure contains Status and Information properties that provide information on the outcome of the call. The Status enumeration can have any of the following values. You need to check ServiceResponse.Status for Completed before you check the result of DoSomething.
Copy
```
public enum ServiceResponseStatus : byte
{
    Unknown = 0x00,
    Completed = 0x01,
    InvalidCredentials = 0x10,        
    ExpectedVersionNoSupportedAtThisEndpoint = 0x20,
    InvalidInput = 0x30,
    ServerUnableToProcessRequest = 0xF0,
}
```
DoSomething—The DoSomething call contains three data structures.
- CallingContext—This data structure defines who is making the call and is used to determine what permissions the caller has to perform any requested operations.
  The CallingContext data structure contains a number of fields that identify where the call is originating from. For the purposes of the Dashboard Service API, there are three essential values.
  - ContextIdentity—This string identifies the caller and is essentially a user name for the Dashboard Service. This is the user account that will be used to validate any operations to be performed. The user account must have sufficient privileges to perform the requested operation.
  - AuthenticationToken—This string is the password associated with the user account used in the ContextIdentity. The Dashboard Service API only supports password authentication.
  - TokenType—This enumeration identifies what type of authentication token is being used. The Dashboard Service API only supports password authentication.
- DoSomethingInput—This data structure holds the input data that is needed by the call. Each Dashboard Service API has its own unique input data structure based on the needs of the call.
- DoSomethingResult—This data structure holds the result of the call. All DoSomethingResult classes are derived from the BaseServiceResult data structure, which contains the success or failure properties that each result needs to communicate. DoSomethingResult contains an OverallStatus property that lists the status of the call and identifies if the operation succeeded or failed. It is different from the ServiceResponse.Status which is only the web service call. The Information property provides additional information to the OverallStatus which may be useful when debugging.
  The OverallStatus enumeration can have any of the following values.
  Copy
```
public enum OverallStatus
{
    Unknown = 0x00,
    Success = 0x01,
    NotAllowed = 0x02,
    InsufficientPermissions = 0x10,
    DuplicateEntry = 0x20,        
    ParentEntityCannotBeResolved = 0x30,
    EntityCannotBeResolved = 0x40,
    PartialFailure = 0x80,
    Failure = 0xFF
}
```
  PartialFailure is an error code that is different from a complete failure when a call has multiple parts. For example, EditDashboardDeviceInfo is a call to edit a list of devices. If one of the devices had a problem (for example, a permissions issue) and the other devices succeeded, then the OverallStatus is listed as PartialFailure. In this case, the result class that is derived from BaseServiceResult will have a status for each input device.

If a boolean or number is not being passed, you may need to include the Specified property. For example, you may need to add HaltOnProvisioningErrorSpecified = "true" if HaltOnProvisioningError is not being passed.