Skip to content

Latest commit

 

History

History
913 lines (809 loc) · 23 KB

api-guide.md

File metadata and controls

913 lines (809 loc) · 23 KB
Raw

API Guide from CA Spring Multimodule

HTTP verbs

CA Spring Multimodule tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

PATCH

Used to update an existing resource, including partial updates

DELETE

Used to delete an existing resource

CA Spring Multimodule tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

The request completed successfully

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s Location header

204 No Content

An update to an existing resource has been applied successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

404 Not Found

The requested resource did not exist

Hypermedia

CA Spring Multimodule uses hypermedia and resources include links to other resources in their responses. Responses are in Hypertext Application from resource to resource. Language (HAL) format. Links can be found beneath the _links key. Users of the API should not create URIs themselves, instead they should use the above-described links to navigate

Index

The index provides the entry point into the service.

Accessing the index

A GET request is used to access the index

Request structure

GET / HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/prs.hal-forms+json
Content-Length: 201

{
  "_links" : {
    "customers" : {
      "href" : "http://localhost:8080/customers/id"
    },
    "customers:search" : {
      "href" : "http://localhost:8080/customers?name=customerName"
    }
  }
}
Path Type Description

_links

Object

Links to resources

CURL request

$ curl 'http://localhost:8080/' -i -X GET

Links

Relation Description

customers

The Customers resource

customers:search

The Search for Customers

Customer REST Service

The customers provides the entry point into the service.

(POST) Creating customers

A POST request is used to access customer creation.

Request structure

POST /customers HTTP/1.1
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 139
Host: localhost:8080

{
  "zip" : "000000-000",
  "number" : "123-A",
  "city" : "city",
  "street" : "street",
  "name" : "Foo Bar",
  "email" : "foo@bar.com"
}
Path Type Description

name

String

The name of the customer

email

String

The email of the customer

street

String

The street of the customer

number

String

The number of the customer

city

String

The city of the customer

zip

String

The zip of the customer

Example response

HTTP/1.1 201 Created
Location: /91f9d915-d1ea-4eb8-97d1-cfabdffc5085
Content-Type: application/prs.hal-forms+json
Content-Length: 129

{
  "_links" : {
    "edit" : {
      "href" : "http://localhost:8080/customers/91f9d915-d1ea-4eb8-97d1-cfabdffc5085"
    }
  }
}

Response headers

Name Description

Location

The location of the created resource

CURL request

$ curl 'http://localhost:8080/customers' -i -X POST \
    -H 'Content-Type: application/hal+json;charset=UTF-8' \
    -d '{
  "zip" : "000000-000",
  "number" : "123-A",
  "city" : "city",
  "street" : "street",
  "name" : "Foo Bar",
  "email" : "foo@bar.com"
}'

Links

Relation Description

edit

Edit customer data

(GET) Retrieving customers by ID

A GET request is used to get the customer by Id.

Request structure

GET /customers/e3119506-030a-4877-a219-389ef21118a4 HTTP/1.1
Accept: application/prs.hal-forms+json
Host: localhost:8080
/customers/{id}
Parameter Description

id

Customer Id

/customers/{id}

CURL request

$ curl 'http://localhost:8080/customers/e3119506-030a-4877-a219-389ef21118a4' -i -X GET \
    -H 'Accept: application/prs.hal-forms+json'

Example response

HTTP/1.1 200 OK
Content-Type: application/prs.hal-forms+json
Content-Length: 1533

{
  "id" : "e3119506-030a-4877-a219-389ef21118a4",
  "name" : "Foo Bar",
  "email" : "foo@bar.com",
  "active" : false,
  "street" : "street",
  "number" : "123-A",
  "city" : "city",
  "zip" : "000000-000",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/customers/e3119506-030a-4877-a219-389ef21118a4"
    }
  },
  "_templates" : {
    "default" : {
      "method" : "PUT",
      "properties" : [ {
        "name" : "city",
        "regex" : "^(?=\\s*\\S).*$",
        "required" : true,
        "type" : "text"
      }, {
        "name" : "email",
        "regex" : "^(?=\\s*\\S).*$",
        "required" : true,
        "type" : "text"
      }, {
        "name" : "name",
        "regex" : "^(?=\\s*\\S).*$",
        "required" : true,
        "type" : "text"
      }, {
        "name" : "number",
        "regex" : "^(?=\\s*\\S).*$",
        "required" : true,
        "type" : "text"
      }, {
        "name" : "street",
        "regex" : "^(?=\\s*\\S).*$",
        "required" : true,
        "type" : "text"
      }, {
        "name" : "zip",
        "regex" : "^(?=\\s*\\S).*$",
        "required" : true,
        "type" : "text"
      } ]
    },
    "activate" : {
      "method" : "PATCH",
      "properties" : [ ],
      "target" : "http://localhost:8080/customers/e3119506-030a-4877-a219-389ef21118a4/activate"
    },
    "deactivate" : {
      "method" : "PATCH",
      "properties" : [ ],
      "target" : "http://localhost:8080/customers/e3119506-030a-4877-a219-389ef21118a4/deactivate"
    }
  }
}

(GET) Finding customers by Name

A GET request is also used to find customers by name.

Request structure

GET /customers?name=Foo%20Bar HTTP/1.1
Accept: application/prs.hal-forms+json
Host: localhost:8080
Parameter Description

name

Customer name to search

CURL request

$ curl 'http://localhost:8080/customers?name=Foo%20Bar' -i -X GET \
    -H 'Accept: application/prs.hal-forms+json'

Response structure

Path Type Description

_embedded.existingCustomerModelList

Array

The customer list

_links

Object

The search made

Example response

HTTP/1.1 200 OK
Content-Type: application/prs.hal-forms+json
Content-Length: 1942

{
  "_embedded" : {
    "existingCustomerModelList" : [ {
      "id" : "e3119506-030a-4877-a219-389ef21118a4",
      "name" : "Foo Bar",
      "email" : "foo@bar.com",
      "active" : false,
      "street" : "street",
      "number" : "123-A",
      "city" : "city",
      "zip" : "000000-000",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/customers/e3119506-030a-4877-a219-389ef21118a4"
        }
      },
      "_templates" : {
        "default" : {
          "method" : "PUT",
          "properties" : [ {
            "name" : "city",
            "regex" : "^(?=\\s*\\S).*$",
            "required" : true,
            "type" : "text"
          }, {
            "name" : "email",
            "regex" : "^(?=\\s*\\S).*$",
            "required" : true,
            "type" : "text"
          }, {
            "name" : "name",
            "regex" : "^(?=\\s*\\S).*$",
            "required" : true,
            "type" : "text"
          }, {
            "name" : "number",
            "regex" : "^(?=\\s*\\S).*$",
            "required" : true,
            "type" : "text"
          }, {
            "name" : "street",
            "regex" : "^(?=\\s*\\S).*$",
            "required" : true,
            "type" : "text"
          }, {
            "name" : "zip",
            "regex" : "^(?=\\s*\\S).*$",
            "required" : true,
            "type" : "text"
          } ]
        },
        "activate" : {
          "method" : "PATCH",
          "properties" : [ ],
          "target" : "http://localhost:8080/customers/e3119506-030a-4877-a219-389ef21118a4/activate"
        },
        "deactivate" : {
          "method" : "PATCH",
          "properties" : [ ],
          "target" : "http://localhost:8080/customers/e3119506-030a-4877-a219-389ef21118a4/deactivate"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/customers?name=Foo%20Bar"
    }
  }
}

(PUT) Updating customers

A PUT request is used to access customer update.

Request structure

PUT /customers/e3119506-030a-4877-a219-389ef21118a4 HTTP/1.1
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 139
Host: localhost:8080

{
  "zip" : "000000-000",
  "number" : "123-A",
  "city" : "city",
  "street" : "street",
  "name" : "Foo Bar",
  "email" : "foo@bar.com"
}
/customers/{id}
Parameter Description

id

Customer Id

/customers/{id}

Path Type Description

name

String

The name of the customer

email

String

The email of the customer

street

String

The street of the customer

number

String

The number of the customer

city

String

The city of the customer

zip

String

The zip of the customer

CURL request

$ curl 'http://localhost:8080/customers/e3119506-030a-4877-a219-389ef21118a4' -i -X PUT \
    -H 'Content-Type: application/hal+json;charset=UTF-8' \
    -d '{
  "zip" : "000000-000",
  "number" : "123-A",
  "city" : "city",
  "street" : "street",
  "name" : "Foo Bar",
  "email" : "foo@bar.com"
}'

Example response

HTTP/1.1 200 OK
Content-Type: application/prs.hal-forms+json
Content-Length: 1533

{
  "id" : "e3119506-030a-4877-a219-389ef21118a4",
  "name" : "Foo Bar",
  "email" : "foo@bar.com",
  "active" : false,
  "street" : "street",
  "number" : "123-A",
  "city" : "city",
  "zip" : "000000-000",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/customers/e3119506-030a-4877-a219-389ef21118a4"
    }
  },
  "_templates" : {
    "default" : {
      "method" : "PUT",
      "properties" : [ {
        "name" : "city",
        "regex" : "^(?=\\s*\\S).*$",
        "required" : true,
        "type" : "text"
      }, {
        "name" : "email",
        "regex" : "^(?=\\s*\\S).*$",
        "required" : true,
        "type" : "text"
      }, {
        "name" : "name",
        "regex" : "^(?=\\s*\\S).*$",
        "required" : true,
        "type" : "text"
      }, {
        "name" : "number",
        "regex" : "^(?=\\s*\\S).*$",
        "required" : true,
        "type" : "text"
      }, {
        "name" : "street",
        "regex" : "^(?=\\s*\\S).*$",
        "required" : true,
        "type" : "text"
      }, {
        "name" : "zip",
        "regex" : "^(?=\\s*\\S).*$",
        "required" : true,
        "type" : "text"
      } ]
    },
    "activate" : {
      "method" : "PATCH",
      "properties" : [ ],
      "target" : "http://localhost:8080/customers/e3119506-030a-4877-a219-389ef21118a4/activate"
    },
    "deactivate" : {
      "method" : "PATCH",
      "properties" : [ ],
      "target" : "http://localhost:8080/customers/e3119506-030a-4877-a219-389ef21118a4/deactivate"
    }
  }
}

Links

Relation Description

self

Resource Self Link

(PATCH) Activate customer

A PATCH request can be used to activate a customer.

Request structure

PATCH /customers/e3119506-030a-4877-a219-389ef21118a4/activate HTTP/1.1
Host: localhost:8080
/customers/{id}/activate
Parameter Description

id

Customer Id

/customers/{id}/activate

CURL request

$ curl 'http://localhost:8080/customers/e3119506-030a-4877-a219-389ef21118a4/activate' -i -X PATCH

Example response

HTTP/1.1 202 Accepted
Content-Type: application/prs.hal-forms+json
Content-Length: 254

{
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/customers/e3119506-030a-4877-a219-389ef21118a4"
    },
    "deactivate" : {
      "href" : "http://localhost:8080/customers/e3119506-030a-4877-a219-389ef21118a4/deactivate"
    }
  }
}

Links

Relation Description

self

Resource Self Link

deactivate

Link to deactivate the customer

(PATCH) Deactivate customer

A PATCH request can be used to deactivate a customer.

Request structure

PATCH /customers/e3119506-030a-4877-a219-389ef21118a4/deactivate HTTP/1.1
Host: localhost:8080
/customers/{id}/deactivate
Parameter Description

id

Customer Id

/customers/{id}/deactivate

CURL request

$ curl 'http://localhost:8080/customers/e3119506-030a-4877-a219-389ef21118a4/deactivate' -i -X PATCH

Example response

HTTP/1.1 202 Accepted
Content-Type: application/prs.hal-forms+json
Content-Length: 250

{
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/customers/e3119506-030a-4877-a219-389ef21118a4"
    },
    "activate" : {
      "href" : "http://localhost:8080/customers/e3119506-030a-4877-a219-389ef21118a4/activate"
    }
  }
}

Links

Relation Description

self

Resource Self Link

activate

Link to activate the customer

References