103616
103616
https://ebookultra.com/download/django-for-apis-build-web-apis-with-
python-and-django-william-s-vincent/
https://ebookultra.com/download/django-for-beginners-4-0-edition-
william-s-vincent/
https://ebookultra.com/download/django-for-beginners-3-1-3-1-edition-
william-s-vincent/
https://ebookultra.com/download/restful-web-apis-1st-edition-leonard-
richardson/
https://ebookultra.com/download/two-scoops-of-django-best-practices-
for-django-1-5-1st-edition-daniel-greenfeld/
Pro Django 2nd Edition Marty Alchin
https://ebookultra.com/download/pro-django-2nd-edition-marty-alchin/
https://ebookultra.com/download/practical-django-projects-second-
edition-james-bennett/
https://ebookultra.com/download/paypal-apis-up-and-running-second-
edition-matthew-a-russell/
https://ebookultra.com/download/flask-web-development-developing-web-
applications-with-python-2nd-edition-miguel-grinberg/
Django for APIs Build web APIs with Python and Django
William S Vincent Digital Instant Download
Author(s): William S Vincent
ISBN(s): 9781735467221, 1735467227
Edition: Paperback
File Details: PDF, 5.35 MB
Year: 2020
Language: english
Django for APIs
William S. Vincent
This is a Leanpub book. Leanpub empowers authors and publishers with the Lean Publishing
process. Lean Publishing is the act of publishing an in-progress ebook using lightweight tools
and many iterations to get reader feedback, pivot until you have the right book and build
traction once you do.
Introduction 1
Prerequisites 1
Why APIs 2
Django REST Framework 3
Why this book 4
Conclusion 4
URLs 24
Webpage 27
Django REST Framework 28
URLs 29
Views 30
Serializers 31
cURL 32
Browsable API 33
Conclusion 34
Tests 72
Django REST Framework 73
URLs 74
Serializers 76
Views 77
Browsable API 78
Conclusion 82
Chapter 6: Permissions 83
Create a new user 83
Add log in to the browsable API 86
AllowAny 90
View-Level Permissions 92
Project-Level Permissions 94
Custom permissions 95
Conclusion 99
Conclusion 138
Conclusion 147
Next Steps 147
Giving Thanks 148
Introduction
The internet is powered by RESTful APIs. Behind the scenes even the simplest online task involves
multiple computers interacting with one another.
An API (Application Programming Interface) is a formal way to describe two computers commu-
nicating directly with one another. And while there are multiple ways to build an API, web APIs—
which allow for the transfer of data over the world wide web—are overwhelmingly structured in
a RESTful (REpresentational State Transfer) pattern.
In this book you will learn how to build multiple RESTful web APIs of increasing complexity from
scratch using Django1 and Django REST Framework2 , one of the most popular and customizable
ways to build web APIs, used by many of the largest tech companies in the world including Insta-
gram, Mozilla, Pinterest, and Bitbucket. This approach is also uniquely well-suited to beginners
because Django’s “batteries-included” approach masks much of the underlying complexity and
security risks involved in creating any web API.
Prerequisites
If you’re brand new to web development with Django, I recommend first reading my previous
book Django for Beginners3 . The first several chapters are available for free online and cover
proper set up, a Hello World app, and a Pages app. The full-length version goes deeper and
covers a Blog website with forms and user accounts as well as a production-ready Newspaper
site that features a custom user model, complete user authentication flow, emails, permissions,
deployment, environment variables, and more.
This background in traditional Django is important since Django REST Framework deliberately
mimics many Django conventions.
1
https://www.djangoproject.com/
2
http://www.django-rest-framework.org/
3
https://djangoforbeginners.com/
Introduction 2
It is also recommended that readers have a basic knowledge of Python itself. Truly mastering
Python takes years, but with just a little bit of knowledge you can dive right in and start building
things.
Why APIs
Django was first released in 2005 and at the time most websites consisted of one large monolithic
codebase. The “back-end” consisted of database models, URLs, and views which interacted with
the “front-end” templates of HTML, CSS, and JavaScript that controlled the presentational layout
of each web page.
However in recent years an “API-first” approach has emerged as arguably the dominant paradigm
in web development. This approach involves formally separating the back-end from the front-
end. It means Django becomes a powerful database and API instead of just a website framework.
Today Django is arguably used more often as just a back-end API rather than a full monolithic
website solution at large companies!
An obvious question at this point is, “Why bother?” Traditional Django works quite well on its own
and transforming a Django site into a web API seems like a lot of extra work. Plus, as a developer,
you then have to write a dedicated front-end in another programming language.
This approach of dividing services into different components, by the way, is broadly known as
Service-oriented architecture4 .
It turns out however that there are multiple advantages to separating the front-end from
the back-end. First, it is arguably much more “future-proof” because a back-end API can be
consumed by any JavaScript front-end. Given the rapid rate of change in front-end libraries–
React5 was only released in 2013 and Vue6 in 2014!–this is highly valuable. When the current
front-end frameworks are eventually replaced by even newer ones in the years to come, the
back-end API can remain the same. No major rewrite is required.
Second, an API can support multiple front-ends written in different languages and frameworks.
Consider that JavaScript is used for web front-ends, while Android apps require the Java
4
https://en.wikipedia.org/wiki/Service-oriented_architecture
5
https://reactjs.org/
6
https://vuejs.org/
Introduction 3
programming language, and iOS apps need the Swift programming language. With a traditional
monolithic approach, a Django website cannot support these various front-ends. But with an
internal API, all three can communicate with the same underlying database back-end!
Third, an API-first approach can be used both internally and externally. When I worked at
Quizlet7 back in 2010, we did not have the resources to develop our own iOS or Android apps.
But we did have an external API available that more than 30 developers used to create their own
flashcard apps powered by the Quizlet database. Several of these apps were downloaded over
a million times, enriching the developers and increasing the reach of Quizlet at the same time.
Quizlet is now a top 20 website in the U.S. during the school year.
The major downside to an API-first approach is that it requires more configuration than a
traditional Django application. However as we will see in this book, the fantastic Django REST
Framework library removes much of this complexity.
There are hundreds and hundreds of third-party apps available that add further functionality to
Django. You can see a complete, searchable list over at Django Packages8 , as well as a curated
list in the awesome-django repo9 . However, among all third-party applications, Django REST
Framework is arguably the killer app for Django. It is mature, full of features, customizable,
testable, and extremely well-documented. It also purposefully mimics many of Django’s tra-
ditional conventions, which makes learning it much faster. And it is written in the Python
programming language, a wonderful, popular, and accessible language.
If you already know Django, then learning Django REST Framework is a logical next step. With a
minimal amount of code, it can transform any existing Django application into a web API.
7
https://quizlet.com/
8
https://djangopackages.org/
9
https://github.com/wsvincent/awesome-django
Introduction 4
I wrote this book because there is a distinct lack of good resources available for developers
new to Django REST Framework. The assumption seems to be that everyone already knows all
about APIs, HTTP, REST, and the like. My own journey in learning how to build web APIs was
frustrating… and I already knew Django well enough to write a book on it!
This book is the guide I wish existed when starting out with Django REST Framework.
Chapter 1 begins with a brief introduction to web APIs and the HTTP protocol. In Chapter 2 we
review the differences between traditional Django and Django REST Framework by building out
a Library book website and then adding an API to it. Then in Chapters 3-4 we build a Todo API
and connect it to a React front-end. The same process can be used to connect any dedicated
front-end (web, iOS, Android, desktop, or other) to a web API back-end.
In Chapters 5-9 we build out a production-ready Blog API which includes full CRUD functionality.
We also cover in-depth permissions, user authentication, viewsets, routers, documentation, and
more.
Complete source code for all chapters can be found online on Github10 .
Conclusion
Django and Django REST Framework is a powerful and accessible way to build web APIs. By the
end of this book you will be able to build your own web APIs from scratch properly using modern
best practices. And you’ll be able to extend any existing Django website into a web API with a
minimal amount of code.
Let’s begin!
10
https://github.com/wsvincent/restapiswithdjango
Chapter 1: Web APIs
Before we start building our own web APIs it’s important to review how the web really works.
After all, a “web API” literally sits on top of the existing architecture of the world wide web and
relies on a host of technologies including HTTP, TCP/IP, and more.
In this chapter we will review the basic terminology of web APIs: endpoints, resources, HTTP
verbs, HTTP status codes, and REST. Even if you already feel comfortable with these terms, I
encourage you to read the chapter in full.
The Internet is a system of interconnected computer networks that has existed since at least the
1960s11 . However, the internet’s early usage was restricted to a small number of isolated networks,
largely government, military, or scientific in nature, that exchanged information electronically.
By the 1980s, many research institutes and universities were using the internet to share data.
In Europe, the biggest internet node was located at CERN (European Organization for Nuclear
Research) in Geneva, Switzerland, which operates the largest particle physics laboratory in the
world. These experiments generate enormous quantities of data that need to be shared remotely
with scientists all around the world.
Compared with today, though, overall internet usage in the 1980s was miniscule. Most people
did not have access to it or even understood why it mattered. A small number of internet
nodes powered all the traffic and the computers using it were primarily within the same, small
networks.
This all changed in 1989 when a research scientist at CERN, Tim Berners-Lee, invented HTTP
and ushered in the modern World Wide Web. His great insight was that the existing hypertext12
11
https://en.wikipedia.org/wiki/Internet
12
https://en.wikipedia.org/wiki/Hypertext
Chapter 1: Web APIs 6
system, where text displayed on a computer screen contained links (hyperlinks) to other
documents, could be moved onto the internet.
His invention, Hypertext Transfer Protocol (HTTP)13 , was the first standard, universal way to
share documents over the internet. It ushered in the concept of web pages: discrete documents
with a URL, links, and resources such as images, audio, or video.
Today, when most people think of “the internet,” they think of the World Wide Web, which is now
the primary way that billions of people and computers communicate online.
URLs
A URL (Uniform Resource Locator) is the address of a resource on the internet. For example, the
Google homepage lives at https://www.google.com.
When you want to go to the Google homepage, you type the full URL address into a web browser.
Your browser then sends a request out over the internet and is magically connected (we’ll cover
what actually happens shortly) to a server that responds with the data needed to render the
Google homepage in your browser.
This request and response pattern is the basis of all web communication. A client (typically a
web browser but also a native app or really any internet-connected device) requests information
and a server responds with a response.
Since web communication occurs via HTTP these are known more formally as HTTP requests
and HTTP responses.
Within a given URL are also several discrete components. For example, consider the Google
homepage located at https://www.google.com. The first part, https, refers to the scheme used.
It tells the web browser how to access resources at the location. For a website this is typically
http or https, but it could also be ftp for files, smtp for email, and so on. The next section,
www.google.com, is the hostname or the actual name of the site. Every URL contains a scheme
and a host.
Many webpages also contain an optional path, too. If you go to the homepage for Python
13
https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol
Chapter 1: Web APIs 7
at https://www.python.org and click on the link for the “About” page you’ll be redirected to
https://www.python.org/about/. The /about/ piece is the path.
• a scheme - https
• a hostname - www.python.org
• and an (optional) path - /about/
Once we know the actual URL of a resource, a whole collection of other technologies must work
properly (together) to connect the client with the server and load an actual webpage. This is
broadly referred to as the internet protocol suite14 and there are entire books written on just
this topic. For our purposes, however, we can stick to the broad basics.
Several things happen when a user types https://www.google.com into their web browser and
hits Enter. First the browser needs to find the desired server, somewhere, on the vast internet.
It uses a domain name service (DNS) to translate the domain name “google.com” into an IP
address15 , which is a unique sequence of numbers representing every connected device on the
internet. Domain names are used because it is easier for humans to remember a domain name
like “google.com” than an IP address like “172.217.164.68”.
After the browser has the IP address for a given domain, it needs a way to set up a consistent
connection with the desired server. This happens via the Transmission Control Protocol (TCP)
which provides reliable, ordered, and error-checked delivery of bytes between two application.
3. The client sends an ACK back to the server confirming the connection
Once the TCP connection is established, the two computers can start communicating via HTTP.
HTTP Verbs
Every webpage contains both an address (the URL) as well as a list of approved actions known as
HTTP verbs. So far we’ve mainly talked about getting a web page, but it’s also possible to create,
edit, and delete content.
Consider the Facebook website. After logging in, you can read your timeline, create a new
post, or edit/delete an existing one. These four actions Create-Read-Update-Delete are known
colloquially as CRUD functionality and represent the overwhelming majority of actions taken
online.
The HTTP protocol contains a number of request methods16 that can be used while requesting
information from a server. The four most common map to CRUD functionality. They are POST,
GET, PUT, and DELETE.
Diagram
To create content you use POST, to read content GET, to update it PUT, and to delete it you use
DELETE.
Endpoints
A website consists of web pages with HTML, CSS, images, JavaScript, and more. But a web API
has endpoints instead which are URLs with a list of available actions (HTTP verbs) that expose
16
https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_method
Chapter 1: Web APIs 9
data (typically in JSON17 , which is the most common data format these days and the default for
Django REST Framework).
For example, we could create the following API endpoints for a new website called mysite.
Diagram
In the first endpoint, /api/users, an available GET request returns a list of all available users. This
type of endpoint which returns multiple data resources is known as a collection.
The second endpoint /api/users/<id> represents a single user. A GET request returns informa-
tion about just that one user.
If we added POST to the first endpoint we could create a new user, while adding DELETE to the
second endpoint would allow us to delete a single user.
We will become much more familiar with API endpoints over the course of this book but
ultimately creating an API involves making a series of endpoints: URLs with associated HTTP
verbs.
A webpage consists of HTML, CSS, images, and more. But an endpoint is just a way to access data
via the available HTTP verbs.
HTTP
We’ve already talked a lot about HTTP in this chapter, but here we will describe what it actually
is and how it works.
HTTP is a request-response protocol between two computers that have an existing TCP connec-
tion. The computer making the requests is known as the client while the computer responding
is known as the server. Typically a client is a web browser but it could also be an iOS app or really
any internet-connected device. A server is a fancy name for any computer optimized to work
17
https://json.org/
Chapter 1: Web APIs 10
over the internet. All we really need to transform a basic laptop into a server is some special
software and a persistent internet connection.
Every HTTP message consists of a status line, headers, and optional body data. For example, here
is a sample HTTP message that a browser might send to request the Google homepage located
at https://www.google.com.
Diagram
GET / HTTP/1.1
Host: google.com
Accept_Language: en-US
The top line is known as the request line and it specifies the HTTP method to use (GET), the path
(/), and the specific version of HTTP to use (HTTP/1.1).
The two subsequent lines are HTTP headers: Host is the domain name and Accept_Language is
the language to use, in this case American English. There are many HTTP headers18 available.
HTTP messages also have an optional third section, known as the body. However we only see a
body message with HTTP responses containing data.
For simplicity, let’s assume that the Google homepage only contained the HTML “Hello, World!”
This is what the HTTP response message from a Google server might look like.
Diagram
HTTP/1.1 200 OK
Date: Mon, 03 Aug 2020 23:26:07 GMT
Server: gws
Accept-Ranges: bytes
Content-Length: 13
Content-Type: text/html; charset=UTF-8
Hello, world!
The top line is the response line and it specifies that we are using HTTP/1.1. The status code 200
OK indicates the request by the client was successful (more on status codes shortly).
18
https://en.wikipedia.org/wiki/List_of_HTTP_header_fields
Chapter 1: Web APIs 11
The next eight lines are HTTP headers. And finally after a line break there is our actual body
content of “Hello, world!”.
Every HTTP message, whether a request or response, therefore has the following format:
Diagram
Response/request line
Headers...
(optional) Body
Most web pages contain multiple resources that require multiple HTTP request/response cycles.
If a webpage had HTML, one CSS file, and an image, three separate trips back-and-forth between
the client and server would be required before the complete web page could be rendered in the
browser.
Status Codes
Once your web browser has executed an HTTP Request on a URL there is no guarantee things will
actually work! Thus there is a quite lengthy list of HTTP Status Codes19 available to accompany
each HTTP response.
You can tell the general type of status code based on the following system:
• 2xx Success - the action requested by the client was received, understood, and accepted
• 3xx Redirection - the requested URL has moved
• 4xx Client Error - there was an error, typically a bad URL request by the client
• 5xx Server Error - the server failed to resolve a request
There is no need to memorize all the available status codes. With practice you will become
familiar with the most common ones such as 200 (OK), 201 (Created), 301 (Moved Permanently),
404 (Not Found), and 500 (Server Error).
19
https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
Chapter 1: Web APIs 12
The important thing to remember is that, generally speaking, there are only four potential
outcomes to any given HTTP request: it worked (2xx), it was redirected somehow (3xx), the client
made an error (4xx), or the server made an error (5xx).
These status codes are automatically placed in the request/response line at the top of every
HTTP message.
Statelessness
A final important point to make about HTTP is that it is a stateless protocol. This means
each request/response pair is completely independent of the previous one. There is no stored
memory of past interactions, which is known as state20 in computer science.
Statelessness brings a lot of benefits to HTTP. Since all electronic communication systems have
signal loss over time, if we did not have a stateless protocol, things would constantly break if
one request/response cycle didn’t go through. As a result HTTP is known as a very resilient
distributed protocol.
The downside however is that managing state is really, really important in web applications. State
is how a website remembers that you’ve logged in and how an e-commerce site manages your
shopping cart. It’s fundamental to how we use modern websites, yet it’s not supported on HTTP
itself.
Historically state was maintained on the server but it has moved more and more to the client,
the web browser, in modern front-end frameworks like React, Angular, and Vue. We’ll learn more
about state when we cover user authentication but remember that HTTP is stateless. This makes
it very good for reliably sending information between two computers, but bad at remembering
anything outside of each individual request/response pair.
REST
REpresentational State Transfer (REST)21 is an architecture first proposed in 2000 by Roy Fielding
20
https://en.wikipedia.org/wiki/State_(computer_science)
21
https://en.wikipedia.org/wiki/Representational_state_transfer
Chapter 1: Web APIs 13
in his dissertation thesis. It is an approach to building APIs on top of the web, which means on
top of the HTTP protocol.
Entire books have been written on what makes an API actually RESTful or not. But there are three
main traits that we will focus on here for our purposes. Every RESTful API:
Any RESTful API must, at a minimum, have these three principles. The standard is important
because it provides a consistent way to both design and consume web APIs.
Conclusion
While there is a lot of technology underlying the modern world wide web, we as developers
don’t have to implement it all from scratch. The beautiful combination of Django and Django
REST Framework handles, properly, most of the complexity involved with web APIs. However it
is important to have at least a broad understanding of how all the pieces fit together.
Ultimately a web API is a collection of endpoints that expose certain parts of an underlying
database. As developers we control the URLs for each endpoint, what underlying data is available,
and what actions are possible via HTTP verbs. By using HTTP headers we can set various levels
of authentication and permission too as we will see later in the book.
Random documents with unrelated
content Scribd suggests to you:
shore; and because in point of fact such dominion, unless in the
neighbourhood of forts, is actually maintained by other means, as by
coastguards and naval vessels. Nevertheless the principle, though
resting largely on hypothesis, had much to recommend it, and it
gradually became incorporated into international law as the rule for
fixing the boundary of the territorial waters. Apart from its intrinsic
merits, its acceptance was perhaps not a little facilitated by the
felicity with which it was expressed. Bynkershoek gave it the form
almost of an aphorism, and the phrase, terræ dominium finitur ubi
finitur armorum vis, has been quoted by almost all later writers.
Wolff, who wrote on the law of nations about the same time,
appears rather to have followed the opinions of Puffendorf. He
argued that the use of the sea next the shore, for fishing and the
collection of things that grow on it, was not inexhaustible, nor its use
for navigation always innocuous; and since it served as a protection
for the adjoining state, it was reasonable that it should be under the
dominion of that state. The inhabitants of the shores had therefore
the right to occupy it “so far as they can maintain their dominion
over it”; and the same was true of straits and bays.1021
Some ten years later Vattel, the pupil and follower of Wolff,
published a work on the law of nations, which is still of authority,
and in which much the same opinions as those of Puffendorf and
Wolff are expressed.1022 On the general question of the appropriation
of the sea the usual statement was made; but Vattel held that a
nation might acquire exclusive rights of navigation and fishery in the
open sea by treaties, but not by prescription, unless in virtue of the
consent or tacit agreement of other nations. Thus “when a nation
that is in possession of the navigation and fishery in certain tracts of
the sea claims an exclusive right of them, and forbids all
participation on the part of other nations, if the others obey that
prohibition with sufficient marks of acquiescence, they tacitly
renounce their own right in favour of that nation, and establish for
her a new right, which she may afterwards lawfully maintain against
them, especially when it is confirmed by long use.” On the other
hand, Vattel states that the uses of the sea near the coast render it
very susceptible of appropriation: it supplies fish, shells, pearls, and
other things, and with respect to all these its use is not
inexhaustible. A maritime people may therefore appropriate and
convert to their own profit “an advantage which nature has placed
within their reach as to enable them conveniently to take possession
of it, in the same manner as they possessed themselves of the
dominion of the land they inhabit.” Vattel does not state his opinion
as to the distance from the coast within which the fisheries may be
appropriated, but from the examples he cites it is evident that the
space might extend considerably beyond the range of guns. “Who
can doubt,” he asks, “that the pearl fisheries of Bahrem and Ceylon
may lawfully become property?” And the same principle may be
applied to floating fish, which appear less liable to be exhausted. If a
people, he says, have on their coast a particular and profitable
fishery of which they can become masters, shall they not be
permitted to appropriate that bounteous gift of nature as an
appendage to the country they possess, and to reserve to
themselves the great advantages which their commerce may thence
derive, if there is sufficient abundance of fish to furnish neighbouring
nations? Thus, Vattel states, the herring fishery on the British coasts
might have been appropriated by the English if they had originally
taken exclusive possession of it, instead of allowing other nations to
take part in it. Another reason for the extension of territorial
dominion over the adjoining sea, “as far as a nation is able to
protect its right,” is the security and welfare of the state; but the
author says it is not easy to fix upon any precise distance. Between
nation and nation, “all that can reasonably be said is that, in general,
the dominion of the state over the neighbouring sea extends as far
as her safety renders it necessary and her power is able to assert it.”
At the time he wrote, “the whole extent of the sea which is within
cannon-shot of the coast is considered as forming part of the
territory; and for that reason a vessel taken under the cannon of a
neutral fortress is not a lawful prize.” The principle that applied to
the adjacent sea applied with much greater force to roads, bays, and
straits, since they were more capable of being possessed, and were
of greater importance to the safety of the country. But such areas
must be “of small extent,” and not great tracts of sea—as Hudson’s
Bay and the Straits of Magellan: a bay “whose entrance can be
defended” might clearly be appropriated.
Towards the close of the century, an Italian author, Azuni, who was
judge in the commercial court at Nice, published a work on maritime
law, in which he dealt with the territorial sea; and adopting the
range of guns as the principle of delimitation, he declared that the
equivalent distance ought to be fixed at three miles, which, he said,
was “without doubt” the farthest a cannon-shot could ever be made
to reach.1031 In this Azuni followed Galiani, making the statement
more definite, and thus we see the three-mile limit put forward by
publicists, as the alternative to the range of guns, before the century
closed. In point of fact, however, it had actually been applied in the
United States a year or two before Azuni wrote;1032 and it is clear
from what he says that no general agreement then existed as to the
extent of the territorial sea, for he complained that the limit was still
undecided,—a statement repeated in his enlarged work, published in
1805,—and he contended that it ought to be fixed by a solemn
treaty between the maritime Powers, as Meadows had suggested a
century before.1033 Although Azuni adopted the principle of cannon
range, and, like Galiani, declared that three miles was the farthest
that a ball or bomb could be thrown,1034 he was of opinion that for
purposes of neutrality, as an asylum against hostilities, the territorial
waters should be extended to two leagues from either shore in the
case of bays and gulfs, which, he says, even when their centre was
at a greater distance than three miles from either shore, were
admitted to be territorial. He even strongly recommended the
adoption of the range of vision as the boundary of neutral waters in
time of war.
From the above review of the opinions of publicists in the latter half
of the eighteenth century, it is evident that there was a general
agreement that the sea, at least as far as the range of guns from the
coast, was accessory to the land: no one doubted that this space at
all events was included within the territorial sea of the neighbouring
country. Almost all the writers went further, and held that the
sovereignty of a state was not confined to gunshot range, but could
be extended to a greater distance from the coast, either for the
security of the state or for jurisdiction, but there was not agreement
as to how far this could be carried. We see, moreover, the growing
tendency to assign a fixed distance as an alternative to cannon
range or as a boundary to neutral waters. Abreu, Valin, and Galiani
placed it at two leagues from the coast, and the same distance is
given by the writer of the article “Mer” in a great French work
published in 17771035—that is, twice the distance of cannon range,
which was said to be one marine league, or three miles.
Next year the United States Congress passed a law authorising the
district courts to take cognisance of all captures made within one
marine league of the American shores;1063 but in the treaty
concluded between Great Britain and the United States in the same
year, it is interesting to observe that the less precise limit of gunshot
was adopted, in the same words as in the treaty of 1786 between
Great Britain and France. The twenty-fifth article of this treaty
provided that neither Government should permit the ships or goods
belonging to the citizens or subjects of the other “to be taken within
cannon-shot of the coast, nor in any of the bays, ports, or rivers of
their territories, by ships of war, or others, having commissions from
any prince, republic, or state whatever.”1064
It may be mentioned here that the claims which have been put
forward by the United States as to the extent of their territorial or
jurisdictional waters have varied greatly on different occasions. The
above declaration to M. Genet was, for instance, repudiated by
President Jefferson as establishing a fixed limit; and it was claimed
that the limit of neutrality should extend “to the Gulf Stream, which
was a natural boundary (!), and within which we ought not to suffer
any hostility to be committed.”1065 On another occasion, in a
controversy about the right of jurisdiction, they claimed that the
extent of neutral immunity off the American coast ought at least to
correspond with the claims maintained by Great Britain around her
own territory, and that no belligerent rights should be exercised
within “the chambers formed by headlands, or anywhere at sea
within the distance of four leagues, or from a right line from one
headland to another.”1066 The American Government endeavoured to
obtain from England in the same year the recognition of a territorial
belt six miles in breadth, and in the draft treaty proposed in 1807 a
distance of five miles was in reality specified.1067
CHAPTER II.
GENERAL ADOPTION OF THE THREE-MILE LIMIT.
It may be here stated that some years later, when American and
British whalers had greatly increased in numbers in Behring Sea, the
Russian officials on several occasions urged their Government to
preserve the sea as a mare clausum,1079 or to prohibit foreign
whalers from approaching the coast within a distance of forty Italian
miles.1080 The Russian Government pointed out in reply that to fix
such a limit would be contrary to the conventions, and might lead to
protests from other Powers, “since no clear and uniform agreement
has yet been arrived at among nations in regard to the limit of
jurisdiction at sea.” In 1847 the Government repeated the
objections, and expressed the opinion that “the limit of a cannon-
shot, that is, about three Italian miles, would alone give rise to no
dispute”; and they further observed that no Power had yet
succeeded in limiting the freedom of fishing in open seas, other
Powers never recognising such pretensions. Subsequently, in 1853,
in consequence of continued complaints as to foreigners fishing in
the sea of Okhotsk, the Russian Government were pressed by the
influential Russian-American Company either to close that great
stretch of waters, as an inland sea, or to prohibit whalers from
approaching close to the shores and whaling in the bays and among
the islands. Instructions were thereupon issued to the commanders
of the Russian cruisers to prevent foreign whalers from entering
bays or gulfs, or from coming “within three Italian miles of the
shores” of Russian America (north of 54° 41´ lat.), the peninsula of
Kamtchatka, Siberia, the Kadjak Archipelago, the Aleutin Islands, the
Pribyloff and Commander Islands, and the others in Behring Sea, as
well as Sakhalin and others; and at the same time it was declared
that while the Sea of Okhotsk, from its geographical position, was a
Russian inland sea, foreigners were to be allowed to take whales
there.1081 Thus the Russian Government adopted at first the principle
of the range of guns, then spoke of this or three Italian miles, and
eventually accepted and enforced, on the great extent of coast
referred to above, the three-mile limit.
Our website is not just a platform for buying books, but a bridge
connecting readers to the timeless values of culture and wisdom. With
an elegant, user-friendly interface and an intelligent search system,
we are committed to providing a quick and convenient shopping
experience. Additionally, our special promotions and home delivery
services ensure that you save time and fully enjoy the joy of reading.
ebookultra.com