Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
533 lines (344 sloc) 12.7 KB

C#

Before you get started!

This documentation assumes you have an active MeshyDB account. If you do not, please create a free account at https://meshydb.com.

Once you verify your account you will need to gather your Account Name and Public Key.

Identify Account Name

Your Account Name can be found under the Account page. See image below:

Account Name under Account

Identify Public Key

Your Public Key can be found under the Clients page under your default tenant. See image below:

Public Key under Clients default tenant

In the following we will assume no other configuration has been made to your account or tenants so we can just begin!

Install SDK

The supporting SDK is open source and you are able to use .Net Framework 4.7.1+ or .Net Core 2.x.

Let's install the MeshyDB.SDK NuGet package with the following command:

Install-Package MeshyDb.SDK

Initialize

The client is used to establish a connection to the API. You will need to provide your Account Name and Public Key from your account and client.

.. tabs::

   .. group-tab:: C#

      .. code-block:: c#

         var client = MeshyClient.Initialize(accountName, publicKey);

      |parameters|

      accountName : :type:`string`, :required:`required`
         Indicates which account you are connecting to.
      publicKey : :type:`string`, :required:`required`
         Public identifier of connecting service.

Register Anonymous User

Anonymous users are great for associating data to people or devices without having them go through any type of user registration.

The example below shows verifying a username is available and registering an anonymous user if the username does not exist.

.. tabs::

   .. group-tab:: C#

      .. code-block:: c#

         var username = "mctesterton";

         var userExists = await client.CheckUserExistAsync(username);

         if (!userExists.Exists)
         {
            await client.RegisterAnonymousUserAsync(username);
         }

      |parameters|

      username : :type:`string`
         Unique identifier for user or device. If it is not provided a username will be automatically generated.

Responses

201 : Created
  • New user has been registered and is now available for use.

Example Result

{
   "id": "5c78cc81dd870827a8e7b6c4",
   "username": "mctesterton",
   "firstName": null,
   "lastName": null,
   "verified": false,
   "isActive": true,
   "phoneNumber": null,
   "emailAddress": null,
   "roles": [],
   "securityQuestions": [],
   "anonymous": true,
   "lastAccessed":"2019-01-01T00:00:00.0000+00:00"
}
400 : Bad request
  • Username is a required field.
  • Anonymous registration is not enabled.
  • Username must be unique.
429 : Too many request
  • You have either hit your API or Database limit. Please review your account.

Login

All data interaction must be done on behalf of a user. This is done to ensure proper authorized access of your data.

The example below shows logging in an anonymous user.

.. tabs::

   .. group-tab:: C#

      .. code-block:: c#

         var connection = await client.LoginAnonymouslyAsync(username);

      |parameters|

      username : :type:`string`, :required:`required`
         Unique identifier for user or device.

Responses

200 : OK
  • Generates new credentials for authorized user.

Example Result

{
  "access_token": "ey...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "ab23cd3343e9328g"
}
400 : Bad request
  • Token is invalid.
  • Client id is invalid.
  • Grant type is invalid.
  • User is no longer active.
  • Invalid Scope.
  • Username is invalid.
  • Password is invalid.
429 : Too many request
  • You have either hit your API or Database limit. Please review your account.

Once we login we can access our connection through a static member.

.. tabs::

   .. group-tab:: C#

      .. code-block:: c#

         connection = MeshyClient.CurrentConnection;

Retrieving Self

When a user is created they have some profile information that helps identify them. We can use this information to link their id back to data that has been created.

The example below shows retrieving information of the user.

.. tabs::

   .. group-tab:: C#

      .. code-block:: c#

         var user = await connection.Users.GetSelfAsync();

      |parameters|

      No parameters provided.

Responses

200 : OK
  • Retrieves information about the authorized user.

Example Result

{
   "id": "5c78cc81dd870827a8e7b6c4",
   "username": "mctesterton",
   "firstName": null,
   "lastName": null,
   "verified": false,
   "isActive": true,
   "phoneNumber": null,
   "emailAddress": null,
   "roles": [],
   "securityQuestions": [],
   "anonymous": true,
   "lastAccessed":"2019-01-01T00:00:00.0000+00:00"
}
401 : Unauthorized
  • User is not authorized to make call.
429 : Too many request
  • You have either hit your API or Database limit. Please review your account.

Create data

Now that a user connection is established you can begin making API requests.

The MeshyDB SDK requires all data extend the MeshData class.

The example below shows a Person represented by a first name, last name and user id.

.. tabs::

   .. group-tab:: C#

      .. code-block:: c#

         // Mesh Name can be overridden by attribute, otherwise by default it is derived from class name
         [MeshName("Person")]
         public class Person : MeshData
         {
            public string FirstName { get; set; }
            public string LastName { get; set; }
            public string UserId { get; set; }
         }

Now that we have a representation of a person we can start making data to write to the API.

The example below shows committing a new person.

.. tabs::

   .. group-tab:: C#

      .. code-block:: c#

         var model = new Person()
         {
            FirstName = "Bob",
            LastName = "Bobson",
            UserId = user.Id
         };

         model = await connection.Meshes.CreateAsync(model);

      |parameters|

      model : :type:`object`, :required:`required`
         Representation of data that *must* extend |meshData|.

Responses

201 : Created
  • Result of newly created mesh data.

Example Result

{
   "_id":"5d438ff23b0b7dd957a765ce",
   "firstName": "Bob",
   "lastName": "Bobson",
   "userId": "5c78cc81dd870827a8e7b6c4"
}
400 : Bad request
  • Mesh name is invalid and must be alpha characters only.
  • Mesh property cannot begin with '$' or contain '.'.
401 : Unauthorized
  • User is not authorized to make call.
403 : Forbidden
  • User has insufficent permission to create meshes or mesh.
429 : Too many request
  • You have either hit your API or Database limit. Please review your account.

Update data

The API allows you to make updates to specific MeshData by targeting the id.

The SDK makes this even simpler since the id can be derived from the object itself along with all it's modifications.

The example below shows modifying the first name and committing those changes to the API.

.. tabs::

   .. group-tab:: C#

      .. code-block:: c#

         model.FirstName = "Robert";

         model = await connection.Meshes.UpdateAsync(model);

      |parameters|

      model : :type:`object`, :required:`required`
         Representation of data that *must* extend |meshData|.

Responses

200 : OK
  • Result of updated mesh data.

Example Result

{
   "_id":"5d438ff23b0b7dd957a765ce",
   "firstName": "Robert",
   "lastName": "Bobson",
   "userId": "5c78cc81dd870827a8e7b6c4"
}
400 : Bad request
  • Mesh name is invalid and must be alpha characters only.
  • Mesh property cannot begin with '$' or contain '.'.
401 : Unauthorized
  • User is not authorized to make call.
403 : Forbidden
  • User has insufficent permission to update meshes or mesh.
429 : Too many request
  • You have either hit your API or Database limit. Please review your account.

Search data

The API allows you to search MeshData using a Linq expression.

The example below shows searching based where the first name starts with Rob.

.. tabs::

   .. group-tab:: C#

      .. code-block:: c#

            Expression<Func<Person, bool>> filter = (Person x) => x.FirstName.StartsWith("Rob");

            var pagedPersonResult = await connection.Meshes
                                                    .SearchAsync<Person>(filter);

      |parameters|

      filter : :type:`object`
         Criteria provided in a Linq expression to limit results.

Responses

200 : OK
  • Mesh data found with given search criteria.

Example Result

{
   "page": 1,
   "pageSize": 25,
   "results":  [{
                  "_id":"5d438ff23b0b7dd957a765ce",
                  "firstName": "Robert",
                  "lastName": "Bobson",
                  "userId": "5c78cc81dd870827a8e7b6c4"
               }],
   "totalRecords": 1
}
400 : Bad request
  • Mesh name is invalid and must be alpha characters only.
  • Filter is in an invalid format. It must be in a valid Mongo DB format.
  • Order by is in an invalid format. It must be in a valid Mongo DB format.
401 : Unauthorized
  • User is not authorized to make call.
403 : Forbidden
  • User has insufficent permission to read meshes or mesh.
429 : Too many request
  • You have either hit your API or Database limit. Please review your account.

In some cases you may need more control on your filtering or ordering. You can optionally provide this criteria in a MongoDB format.

Delete data

The API allows you to delete a specific MeshData by targeting the id.

The example below shows deleting the data from the API by providing the object.

Deleted data is not able to be recovered. If you anticipate the need to recover this data please implementing a Soft Delete.

.. tabs::

   .. group-tab:: C#

      .. code-block:: c#

            var id = model.Id;

            await connection.Meshes.DeleteAsync<Person>(id);

      |parameters|

      id : :type:`string`, :required:`required`
         Identifier of record that must be deleted.

Responses

204 : No Content
  • Mesh has been deleted successfully.
400 : Bad request
  • Mesh name is invalid and must be alpha characters only.
401 : Unauthorized
  • User is not authorized to make call.
403 : Forbidden
  • User has insufficent permission to delete meshes or mesh.
404 : Not Found
  • Mesh data was not found.
429 : Too many request
  • You have either hit your API or Database limit. Please review your account.

Sign out

The MeshyDB SDK manages a single connection to the API.

The Meshy SDK handles token management, this includes refresh tokens used to maintain a user's connection.

As a result it is recommended to implement Sign Out to ensure the current user is logged out and all refresh tokens are revoked.

The example below shows signing out of the currently established connection.

.. tabs::

   .. group-tab:: C#

      .. code-block:: c#

         await connection.SignoutAsync();

      |parameters|

      No parameters provided. The connection is aware of who needs to be signed out.

Responses

200 : OK
  • Identifies successful logout.
400 : Bad request
  • Invalid client id.
  • Token is missing.
  • Unsupported Token type.
429 : Too many request
  • You have either hit your API or Database limit. Please review your account.

Not seeing something you need? Feel free to give us a chat or contact us at support@meshydb.com.

You can’t perform that action at this time.