Enum поле в XML API

Проектируя публичное API очень важно понимать, что Ваше API будут использовать другие разработчики различного уровня, которые будут вынуждены разбираться в нем с нуля. Именно поэтому важную роль здесь играет простота и понятность созданного Вами API. Интуитивно-понятное API намного проще осваивать, и тем более использовать. Любое API подразумевает обмен сообщениями между "клиентом" и "сервером", и зачастую такие сообщения удобно записывать в виде XML. Стандартная ситуация, Вы формируете некий XML и посылаете его на сервер, сервер разбирает его и отвечает Вам другим XML (XML API). К примеру, это может быть запрос аутентификации:

<request>

    <auth>

        <login>ilya</login>

        <password>*****</password>

    </auth>

</request>

и соответственно ответ на запрос со стороны сервера будет выглядеть следующим образом:

<response>

    <result>42</result>

 

    <!-- Остальные поля ответа... -->

</response>

XML elements или XML attributes

Всегда проектируя структуру XML файла, Вы наверняка задумывались, где хранить данные: в атрибуте (XML attribute) или все-таки в узле (XML element). Это довольно важный вопрос, который нужно решить раз и навсегда еще на этапе проектирования XSD схемы, иначе последующее переделывание XSD схемы не есть хорошая практика. Обратите внимание на два XML файла:

<?xml version="1.0" encoding="utf-8" ?>

<!-- Храним данные в атрибуте -->

<root>

    <child data="some data"></child>   

</root>

 

 

<?xml version="1.0" encoding="utf-8" ?>

<!-- Храним данные в узле -->

<root>

    <child>

        <data>

            some data

        </data>

    </child>

</root>

XML-документация

Когда вы программируете, помните, что код пишется людьми для людей, а компилятор проглотит любой синтаксически правильный код. Согласитесь, что код с комментариями намного проще понять, а библиотеку с документацией намного удобнее использовать. Представьте ситуацию, перед Вами поставлена задача: поддерживать техническую документацию проекта в актуальном состоянии. Подумав, вы понимаете, что поддерживать её вручную с ростом проекта будет все сложнее и сложнее, поэтому приходите выводу, что оптимальным решением будет использовать автоматические средства генерации документации, но для этого, Ваши комментарии должны быть представлены так, чтобы их было бы удобно обрабатывать(только не надо изобретать велосипеды)... XML!

Visual studio XML intellisense

Порой очень удобно разрабатывать XML документы в Visual studio (intellisense) особенно при наличии схемы XSD.

Именование пространств имен в XML, XSD

В своих проектах я использую, на мой взгляд очень удобную схему именования пространств имен в XML, XSD документах.