anchor.diff:  
   include::{snippets}/create-submission/http-response.adoc[]
   
  -The `location` header in the response has the URL for the created submission. You will need this when adding things to the submission.
  -
  -== Add samples
  -
  -Using the link from the submission labelled `samples:create`, `POST` a sample object:
  -
  -include::{snippets}/create-sample/curl-request.adoc[]
  -
  -
  -Note that the submission field above contains the URL to the submission, this allows the records to be linked together.
  -
  -This will return a response to show that the sample record has been created:
  -
  -include::{snippets}/create-sample/http-response.adoc[]
  -
  +The `location` header in the response has the URL for the created submission. You will need this when adding things to
  +the submission.
  +
  +== Adding samples
  +
  +We'll start by adding samples. It's a good template for adding anything to a submission - while the details in the
  +documents change, the process is the same across all types of document.
   
   === Naming samples (and everything else)
   
  
positive.code: the record within the submission system. Each alias should be unique within the records of that type owned by a team.
  Using an alias for a second time in another submission will cause the record to be overwritten.
  
  === Sample documents
  
  The description of a sample should normally include a taxonomic code to describe the species classification. This should
  be an entry from the taxonomy database curated at https://www.ncbi.nlm.nih.gov/taxonomy/[NCBI]. EMBL-EBI provide a
  http://www.ebi.ac.uk/ena/browse/taxonomy-service[service] to search for and look up taxonomic entries and this is used
  when the submission interface checks sample documents.
  
  We will accept sample records for display in https://www.ebi.ac.uk/biosamples/[BioSamples] without a taxon ID, but
  you will not be able to use the sample record when submitting data the experimental data archives without a taxon ID.
  
  If you use a taxon ID, it must be one marked as 'submittable' in the taxonomy database.
  
  
  === Validation
  
  Descriptive data is checked at two points during submission:
  
   1. When sent to the API server, through `POST`, `PUT` and `PATCH` requests. At this point the sent must be match the expected syntax, and be identified with an alias.
   2. Once accepted by the API server, it is sent to a suite of validators to ensure it meets the requirements of the relevant archives or project.
  
  The second stage of validation is more in depth, and takes longer. Clients can poll for `ValidationResults` for each
  submitted document, and for a submission. You will not be able to complete a submission until validation
  have completed and no errors have been found.
  
  TODO add example of getting validation results
  
  === Updating a sample
  
  
negative.code: The examples in this walkthrough use https://en.wikipedia.org/wiki/CURL[curl] to interact with the server, but you can
  use the API with any programming language.
  
  The submission process follows these steps:
  
   1. Create a submission
   2. Add documents describing your data to the submission (samples, studies, etc...)
   3. Get feedback and amend documents if necessary
   4. Tell us the submission is ready to go
  
  At this point we will send the data to the appropriate archive or archives. They will send reports on their progress
  with your data and accessions back to us.
  
  This guide assumes some familiarity with REST APIs and the HTTP protocol.
  
  == Log in
  
  *TODO* we will add a section describing how to get an authorisation token and what to do with it.
  
  == Fetch the API root
  
  We recommend that you start from the root endpoint and follow the _links_ given in the `_links` section of the
  response, instead of hard-coding each API endpoint. This will insulate you from future changes to the submission system
  architecture or URL structure.
  
  include::{snippets}/root-endpoint/curl-request.adoc[]
  
  