|
| 1 | +Using Evelyn |
| 2 | +============ |
| 3 | + |
| 4 | +We'll assume that you've got the sample client and server running. Now let's try to do something with it. |
| 5 | + |
| 6 | +Accessing the REST Server |
| 7 | +------------------------- |
| 8 | + |
| 9 | +The Evelyn REST API endpoints are specified using `OpenAPI <https://www.openapis.org/>`_ and documented using using `Swagger UI <https://swagger.io/tools/swagger-ui/>`_. By default, the sample server host is configured to allow us to access port 2316, and so we can inspect the API in a browser by navigating to ``http://localhost:2316/swagger/``. |
| 10 | + |
| 11 | +.. image:: ../images/swagger-1.png |
| 12 | + |
| 13 | +If you don't see this, it might be because something else is already using port 2316. If this is the case, you'll need to modify the port forwarding configuration for evelyn-server-host in ``./src/docker-compose.yml`` to specify a different port. |
| 14 | + |
| 15 | +When the server runs for the first time, it will set up a default account for us and add create some sample data to get us started. Lets check it is all set up correctly: |
| 16 | + |
| 17 | +- In Swagger UI, expand the `GET /api/projects` section |
| 18 | +- Click the `Try it out` button |
| 19 | +- Click the `Execute` button |
| 20 | + |
| 21 | +In Evelyn, a project is a logical collection of feature toggles and environments. The ``/api/projects`` endpoint returns us a list of all the projects on our account. When we click the `Execute` button, Swagger will make a call to this endpoint. The response should look something like this: |
| 22 | + |
| 23 | +.. code-block:: json |
| 24 | +
|
| 25 | + { |
| 26 | + "accountId": "e70fd009-22c4-44e0-ab13-2b6edaf0bbdb", |
| 27 | + "projects": [ |
| 28 | + { |
| 29 | + "id": "8f73d020-96c4-407e-8602-74fd4e2ed08b", |
| 30 | + "name": "My First Project" |
| 31 | + } |
| 32 | + ], |
| 33 | + "created": "2018-05-27T15:58:13.6253741+00:00", |
| 34 | + "createdBy": "SystemUser", |
| 35 | + "lastModified": "2018-05-27T15:58:30.7611496+00:00", |
| 36 | + "lastModifiedBy": "SystemUser", |
| 37 | + "version": 1 |
| 38 | + } |
| 39 | +
|
| 40 | +We can see here that our account ID is ``e70fd009-22c4-44e0-ab13-2b6edaf0bbdb``, and we have a project called ``My First Project`` which has the ID ``8f73d020-96c4-407e-8602-74fd4e2ed08b``. |
| 41 | + |
| 42 | +Now we know the ID of the project, lets now get more details about it: |
| 43 | + |
| 44 | +- Expand the `GET /api/projects/{id}` section |
| 45 | +- Click the `Try it out` button |
| 46 | +- In the `id` input box, enter the id of the project, ``8f73d020-96c4-407e-8602-74fd4e2ed08b`` |
| 47 | +- Click the `Execute` button |
| 48 | + |
| 49 | +The response should look something like this: |
| 50 | + |
| 51 | +.. code-block:: json |
| 52 | +
|
| 53 | + { |
| 54 | + "id": "8f73d020-96c4-407e-8602-74fd4e2ed08b", |
| 55 | + "name": "My First Project", |
| 56 | + "environments": [ |
| 57 | + { |
| 58 | + "key": "my-first-environment" |
| 59 | + } |
| 60 | + ], |
| 61 | + "toggles": [ |
| 62 | + { |
| 63 | + "key": "my-first-toggle", |
| 64 | + "name": "My First Toggle" |
| 65 | + } |
| 66 | + ], |
| 67 | + "created": "2018-05-27T15:58:30.7715006+00:00", |
| 68 | + "createdBy": "SystemUser", |
| 69 | + "lastModified": "2018-05-27T15:58:30.8970043+00:00", |
| 70 | + "lastModifiedBy": "SystemUser", |
| 71 | + "version": 2 |
| 72 | + } |
| 73 | +
|
| 74 | +We can see that the project has a single environment, ``my-first-environment`` and has one toggle, ``my-first-toggle``. |
| 75 | + |
| 76 | +So far so good. Now lets turn our attention to the client. |
| 77 | + |
| 78 | + |
| 79 | +Using the Client |
| 80 | +---------------- |
| 81 | + |
| 82 | +An application that uses the Evelyn client must be configured to connect to the server to retrieve the current toggle states for a particular enviroment and project. |
| 83 | + |
| 84 | +The sample client host is already configured to get the toggle state for the sample project and environment that was created when we started the server; you can find this configuration in ``.\src\Evelyn.Client.Host\Startup.cs``. Note that in this class we also start a background service, which is used to poll the server for the current state. |
| 85 | + |
| 86 | +Now, take a look in the ``ClassWithToggle`` class. You'll see we're injecting an ``IEvelynClient`` in the constructor. This interface lets us access the toggle states for our chosen environment. We use the ``GetToggleState`` method on this interface to get the current state of our ``my-first-toggle`` toggle, and then use this to decide which block of code to execute. |
| 87 | + |
| 88 | +Look at the logging output from sample - if you're using Visual Studio this will be in in the Output window, or if you're running on the command line it'll be directly in your shell. You should see something like this... |
| 89 | + |
| 90 | +.. code-block:: text |
| 91 | + |
| 92 | + This code is only called when the toggle is OFF. |
| 93 | +
|
| 94 | +It's clear from this that our execution path is currently that specified for when the toggle is turned off. |
| 95 | + |
| 96 | +Changing toggle state |
| 97 | +--------------------- |
| 98 | + |
| 99 | +Now, lets change the state of our toggle. We can do this either through the Swagger UI or via the Evelyn Management UI (if you've set it up): |
| 100 | + |
| 101 | +Changing toggle state in Swagger UI |
| 102 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 103 | + |
| 104 | +- Expand the `POST /api/projects/{projectId}/environments/{environmentKey}/toggles/{toggleKey}/change-state` section |
| 105 | +- Click the `Try it out` button |
| 106 | +- In the `projectId` input box, enter the id of the project, ``8f73d020-96c4-407e-8602-74fd4e2ed08b`` |
| 107 | +- In the `environmentKey` input box, enter the key of our environment, ``my-first-environment`` |
| 108 | +- In the ``toggleKey`` input box, enter the key of our toggle, ``my-first-toggle`` |
| 109 | +- In the `message Body` input box, enter this: |
| 110 | +.. code-block:: json |
| 111 | +
|
| 112 | + { |
| 113 | + "expectedToggleStateVersion": 0, |
| 114 | + "state": "True" |
| 115 | + } |
| 116 | +- Click the `Execute` button |
| 117 | + |
| 118 | +Changing toggle state in Evelyn Management UI |
| 119 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 120 | + |
| 121 | +- From the dashboard, select `My First Project` |
| 122 | +- Select `my-first-environment` from the list of environments |
| 123 | +- Find `my-first-toggle` in the list of toggles, and click its icon to change the state from ``OFF`` to ``ON`` |
| 124 | + |
| 125 | + |
| 126 | +Now look at the logs again.... |
| 127 | + |
| 128 | +.. code-block:: text |
| 129 | + |
| 130 | + This code is only called when the toggle is OFF. |
| 131 | + Toggle state has changed. |
| 132 | + This code is only called when the toggle is ON. |
| 133 | +
|
| 134 | +Now, we're going through the other code block! So, in changing the toggle state, we've changed the behaviour of our application. |
| 135 | + |
| 136 | + |
0 commit comments